Amazon SP-API Integration Flow for CONA

This document describes how CONA integrates with Amazon SP-API using two reports:

SC_VAT_TAX_REPORT → Invoices & Credit Notes
Settlement Report → Payments (virtual bank account)

Overview

CONA treats Amazon as a virtual bank account where all transactions flow through:

┌─────────────────────────────────────────────────────────────────────┐
│                    "AMAZON VIRTUAL ACCOUNT"                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  MONEY IN (Credits)                    MONEY OUT (Debits)           │
│  ──────────────────                    ─────────────────            │
│                                                                     │
│  + Customer Payment (Principal)        - Amazon Commission          │
│  + Customer Payment (Tax)              - FBA Fees                   │
│  + Customer Payment (Shipping)         - Variable Closing Fee       │
│  + Commission Refund (on refund)       - Refund to Customer         │
│                                        - Refund Commission Fee      │
│                                        - Storage Fees               │
│                                        - Advertising Fees           │
│                                        - PAYOUT TO BANK →           │
│                                                                     │
│  Balance = Settlement Amount                                        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Document Types & Data Sources

CONA Document	Amazon Report	Transaction Type	Trigger
Invoice	`SC_VAT_TAX_REPORT`	`SHIPMENT`	Daily sync
Credit Note	`SC_VAT_TAX_REPORT`	`REFUND`	Daily sync
Payments	`GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE`	All rows	Settlement closed

SC_VAT_TAX_REPORT (Invoices & Credit Notes)

The SC_VAT_TAX_REPORT is the single source for creating invoices and credit notes.

What It Contains

Order ID and Order Item ID
Transaction Type: SHIPMENT, REFUND, RETURN
Buyer Details: Name, address, company name, VAT number
Product Details: ASIN, SKU, product name, quantity
Pricing: VAT-inclusive (gross) and VAT-exclusive (net) amounts
VAT Details: VAT rate, tax collection model
Amazon Invoice Reference: Invoice number, date, URL
B2B Indicators: Is business order, purchase order number

How We Use It

// Request report for yesterday's transactions
const reportId = await client.reports.createReport({
  reportType: "SC_VAT_TAX_REPORT",
  marketplaceIds: ["A1PA6795UKMFR9"],
  dataStartTime: yesterday,
  dataEndTime: today,
});

// Parse downloaded report
const rows = parseVATTaxReport(reportContent);

// Split by transaction type
const shipments = rows.filter((r) => r.transactionType === "SHIPMENT"); // → Invoices
const refunds = rows.filter((r) => r.transactionType === "REFUND"); // → Credit Notes

Requirements

VCS Enrollment: VAT Calculation Service must be enabled
Tax Invoicing Role: “Tax Invoicing (Restricted)” permission
EU Marketplaces: DE, FR, IT, ES, UK, NL, BE, PL, SE, IE

Benefits Over Orders API

Aspect	Orders API	SC_VAT_TAX_REPORT
Data retrieval	Per-order API calls	Single bulk report
VAT data	Must calculate	Pre-calculated net/gross
B2B VAT number	Separate API + permission	Included in report
Customer address	Separate API + PII permission	Included in report
Invoice reference	Not available	Amazon’s invoice number
Rate limits	Subject to throttling	One report request

Settlement Report (Payments)

The Settlement Report records all money movement in the Amazon virtual bank account.

What It Contains

Each row in the settlement report represents a transaction:

Column	Description
`settlement-id`	Unique settlement period ID
`settlement-start-date`	Period start
`settlement-end-date`	Period end
`deposit-date`	When funds transferred to bank
`total-amount`	Net settlement amount
`currency`	Settlement currency
`transaction-type`	Order, Refund, Service Fee, etc.
`order-id`	Related Amazon order
`amount-type`	ItemPrice, Commission, FBAFee, etc.
`amount-description`	Detailed description
`amount`	Transaction amount

Transaction Types

type SettlementTransactionType =
  | "Order" // Customer payment received
  | "Refund" // Customer refund issued
  | "Service Fee" // Amazon service fees (storage, ads)
  | "Adjustment" // Manual adjustments
  | "Transfer" // Payout to bank account
  | "Reserve" // Reserve hold/release
  | "other-transaction"; // Other transactions

How We Use It

// Request settlement report (auto-generated by Amazon when settlement closes)
const reports = await client.reports.getReports({
  reportTypes: ["GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE"],
  processingStatuses: ["DONE"],
  createdSince: lastSyncDate,
});

// Download and parse each settlement report
for (const report of reports) {
  const content = await downloadReport(report.reportDocumentId);
  const rows = parseSettlementReport(content);

  // Group by order for reconciliation
  const byOrder = groupByOrderId(rows);

  // Create payments in CONA
  for (const [orderId, transactions] of byOrder) {
    // Link to invoice/credit note by order ID
    await createPaymentsFromSettlement(orderId, transactions);
  }
}

Payment Categories

From settlement report rows, we create these payment types:

Settlement Row Type	CONA Payment Type	Direction
Order + ItemPrice	`customer_payment`	IN
Order + Commission	`amazon_fee`	OUT
Order + FBAFee	`amazon_fee`	OUT
Refund + ItemPrice	`customer_refund`	OUT
Refund + Commission	`fee_refund`	IN
Service Fee	`service_fee`	OUT
Transfer	`payout`	OUT
Adjustment	`adjustment`	IN/OUT

Complete Sync Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    AMAZON DAILY SYNC WORKFLOW                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 1: REQUEST VAT TAX REPORT                               │   │
│  │ ─────────────────────────────                                │   │
│  │                                                              │   │
│  │ createReport({                                               │   │
│  │   reportType: "SC_VAT_TAX_REPORT",                           │   │
│  │   marketplaceIds: [...euMarketplaces],                       │   │
│  │   dataStartTime: yesterday,                                  │   │
│  │   dataEndTime: today,                                        │   │
│  │ })                                                           │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 2: POLL FOR REPORT COMPLETION                           │   │
│  │ ─────────────────────────────────                            │   │
│  │                                                              │   │
│  │ while (status !== "DONE") {                                  │   │
│  │   await sleep(60_000); // 1 minute                           │   │
│  │   status = await getReport(reportId);                        │   │
│  │ }                                                            │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 3: DOWNLOAD & PARSE REPORT                              │   │
│  │ ───────────────────────────────                              │   │
│  │                                                              │   │
│  │ const doc = await getReportDocument(reportDocumentId);       │   │
│  │ const content = await downloadAndDecompress(doc.url);        │   │
│  │ const orders = parseVATTaxReport(content);                   │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 4: CREATE INVOICES (SHIPMENT transactions)              │   │
│  │ ───────────────────────────────────────────                  │   │
│  │                                                              │   │
│  │ const shipments = orders.filter(o =>                         │   │
│  │   o.transactionType === "SHIPMENT"                           │   │
│  │ );                                                           │   │
│  │                                                              │   │
│  │ for (const order of shipments) {                             │   │
│  │   if (!existsInvoice(order.orderId)) {                       │   │
│  │     createInvoice({                                          │   │
│  │       customer: order.buyerName,                             │   │
│  │       address: order.buyerAddress,                           │   │
│  │       vatNumber: order.buyerVatNumber,                       │   │
│  │       lineItems: order.items,                                │   │
│  │       total: order.grandTotalGross,                          │   │
│  │       vat: order.grandTotalGross - order.grandTotalNet,      │   │
│  │     });                                                      │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 5: CREATE CREDIT NOTES (REFUND transactions)            │   │
│  │ ─────────────────────────────────────────────                │   │
│  │                                                              │   │
│  │ const refunds = orders.filter(o =>                           │   │
│  │   o.transactionType === "REFUND"                             │   │
│  │ );                                                           │   │
│  │                                                              │   │
│  │ for (const refund of refunds) {                              │   │
│  │   if (!existsCreditNote(refund.orderId, refund.date)) {      │   │
│  │     createCreditNote({                                       │   │
│  │       originalOrderId: refund.orderId,                       │   │
│  │       customer: refund.buyerName,                            │   │
│  │       address: refund.buyerAddress,                          │   │
│  │       lineItems: refund.items,                               │   │
│  │       total: refund.grandTotalGross,                         │   │
│  │     });                                                      │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ STEP 6: PROCESS SETTLEMENT REPORTS (Payments)                │   │
│  │ ─────────────────────────────────────────────                │   │
│  │                                                              │   │
│  │ const settlements = await getReports({                       │   │
│  │   reportTypes: ["GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE"],  │   │
│  │   processingStatuses: ["DONE"],                              │   │
│  │   createdSince: lastSettlementSync,                          │   │
│  │ });                                                          │   │
│  │                                                              │   │
│  │ for (const settlement of settlements) {                      │   │
│  │   const rows = await downloadSettlementReport(settlement);   │   │
│  │   const payments = createPaymentsFromSettlement(rows);       │   │
│  │                                                              │   │
│  │   // Link payments to invoices/credit notes by order ID      │   │
│  │   for (const payment of payments) {                          │   │
│  │     linkPaymentToDocument(payment);                          │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Sync Frequency

Sync Type	Frequency	Report
Invoices	Daily	`SC_VAT_TAX_REPORT`
Credit Notes	Daily	`SC_VAT_TAX_REPORT`
Payments	On close	`GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE`

Note: Settlement reports are auto-generated by Amazon when a settlement period closes (typically every 14 days). You poll for new settlement reports and process them as they become available.

Payment Types in CONA

type AmazonPaymentType =
  | "customer_payment" // Customer pays for order (IN)
  | "customer_refund" // Refund to customer (OUT)
  | "amazon_fee" // Fee charged by Amazon (OUT)
  | "fee_refund" // Fee returned on refund (IN)
  | "service_fee" // Standalone fee (OUT)
  | "adjustment" // Adjustment (IN or OUT)
  | "payout" // Transfer to bank (OUT)
  | "reserve"; // Reserve hold (OUT) / release (IN)

Example: Complete Order Lifecycle

1. Order Ships → Invoice Created (from SC_VAT_TAX_REPORT)

// VAT report row (transactionType: "SHIPMENT")
{
  orderId: "902-3159896-1390916",
  transactionType: "SHIPMENT",
  transactionDate: "2024-01-20T19:49:35Z",
  buyerName: "Max Mustermann",
  buyerAddress: "Musterstraße 123, 10115 Berlin, DE",
  buyerVatNumber: null, // B2C order
  productName: "Wireless Headphones",
  quantity: 1,
  itemPriceGross: 122.82,
  itemPriceNet: 103.21,
  vatRate: 0.19,
  currency: "EUR",
}

// → Creates INVOICE in CONA
{
  type: "invoice",
  externalId: "902-3159896-1390916",
  customer: "Max Mustermann",
  total: 122.82,
  vat: 19.61,
  netTotal: 103.21,
}

2. Settlement Closes → Payments Created (from Settlement Report)

// Settlement report rows for this order
[
  { orderId: "902-3159896-1390916", amountType: "ItemPrice", amount: 122.82 },
  { orderId: "902-3159896-1390916", amountType: "Commission", amount: -14.99 },
  { orderId: "902-3159896-1390916", amountType: "FBAPerUnitFulfillmentFee", amount: -3.50 },
]

// → Creates PAYMENTS in CONA
{
  type: "customer_payment",
  amount: 122.82,
  orderId: "902-3159896-1390916",
  allocatedTo: "INV-001", // Linked to invoice
}

{
  type: "amazon_fee",
  feeType: "Commission",
  amount: -14.99,
  orderId: "902-3159896-1390916",
}

{
  type: "amazon_fee",
  feeType: "FBAPerUnitFulfillmentFee",
  amount: -3.50,
  orderId: "902-3159896-1390916",
}

// Net in Amazon account: 122.82 - 14.99 - 3.50 = €104.33

3. Refund Issued → Credit Note Created (from SC_VAT_TAX_REPORT)

// VAT report row (transactionType: "REFUND")
{
  orderId: "902-3159896-1390916",
  transactionType: "REFUND",
  transactionDate: "2024-01-28T10:30:00Z",
  buyerName: "Max Mustermann",
  buyerAddress: "Musterstraße 123, 10115 Berlin, DE",
  productName: "Wireless Headphones",
  quantity: 1,
  itemPriceGross: -122.82, // Negative for refund
  itemPriceNet: -103.21,
  currency: "EUR",
}

// → Creates CREDIT NOTE in CONA
{
  type: "credit_note",
  externalId: "refund_902-3159896-1390916_2024-01-28",
  originalOrderId: "902-3159896-1390916",
  total: -122.82,
}

4. Refund Settlement → Refund Payments Created

// Settlement report rows for refund
[
  { orderId: "902-3159896-1390916", transactionType: "Refund", amountType: "ItemPrice", amount: -122.82 },
  { orderId: "902-3159896-1390916", transactionType: "Refund", amountType: "Commission", amount: 14.99 },
  { orderId: "902-3159896-1390916", transactionType: "Refund", amountType: "RefundCommission", amount: -5.00 },
]

// → Creates PAYMENTS in CONA
{
  type: "customer_refund",
  amount: -122.82,
  orderId: "902-3159896-1390916",
  allocatedTo: "CN-001", // Linked to credit note
}

{
  type: "fee_refund",
  feeType: "Commission",
  amount: 14.99, // Commission returned
  orderId: "902-3159896-1390916",
}

{
  type: "amazon_fee",
  feeType: "RefundCommission",
  amount: -5.00, // Refund processing fee
  orderId: "902-3159896-1390916",
}

API Rate Limits

API	Rate	Burst
`createReport`	0.0167/sec	15
`getReport`	2/sec	15
`getReportDocument`	0.0222/sec	10

Getting Started

Core CONA Logic

Development Setup

Guides

E2E Tests

Integrations

RFC

Amazon integration flow

Amazon SP-API Integration Flow for CONA

Overview

Document Types & Data Sources

SC_VAT_TAX_REPORT (Invoices & Credit Notes)

What It Contains

How We Use It

Requirements

Benefits Over Orders API

Settlement Report (Payments)

What It Contains

Transaction Types

How We Use It

Payment Categories

Complete Sync Flow

Sync Frequency

Payment Types in CONA

Example: Complete Order Lifecycle

1. Order Ships → Invoice Created (from SC_VAT_TAX_REPORT)

2. Settlement Closes → Payments Created (from Settlement Report)

3. Refund Issued → Credit Note Created (from SC_VAT_TAX_REPORT)

4. Refund Settlement → Refund Payments Created

API Rate Limits

​Amazon SP-API Integration Flow for CONA

​Overview

​Document Types & Data Sources

​SC_VAT_TAX_REPORT (Invoices & Credit Notes)

​What It Contains

​How We Use It

​Requirements

​Benefits Over Orders API

​Settlement Report (Payments)

​What It Contains

​Transaction Types

​How We Use It

​Payment Categories

​Complete Sync Flow

​Sync Frequency

​Payment Types in CONA

​Example: Complete Order Lifecycle

​1. Order Ships → Invoice Created (from SC_VAT_TAX_REPORT)

​2. Settlement Closes → Payments Created (from Settlement Report)

​3. Refund Issued → Credit Note Created (from SC_VAT_TAX_REPORT)

​4. Refund Settlement → Refund Payments Created

​API Rate Limits

​Related Documentation

Amazon SP-API Integration Flow for CONA

Overview

Document Types & Data Sources

SC_VAT_TAX_REPORT (Invoices & Credit Notes)

What It Contains

How We Use It

Requirements

Benefits Over Orders API

Settlement Report (Payments)

What It Contains

Transaction Types

How We Use It

Payment Categories

Complete Sync Flow

Sync Frequency

Payment Types in CONA

Example: Complete Order Lifecycle

1. Order Ships → Invoice Created (from SC_VAT_TAX_REPORT)

2. Settlement Closes → Payments Created (from Settlement Report)

3. Refund Issued → Credit Note Created (from SC_VAT_TAX_REPORT)

4. Refund Settlement → Refund Payments Created

API Rate Limits

Related Documentation