> ## Documentation Index > Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Amazon integration flow # 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 ```typescript theme={null} // 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 ```typescript theme={null} 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 ```typescript theme={null} // 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 ```typescript theme={null} 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) ```typescript theme={null} // 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) ```typescript theme={null} // 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) ```typescript theme={null} // 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 ```typescript theme={null} // 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 | ## Related Documentation * [Amazon SP-API Docs](https://developer-docs.amazon.com/sp-api/docs/welcome) * [Reports API Reference](https://developer-docs.amazon.com/sp-api/docs/reports-api-v2021-06-30-reference) * [SC\_VAT\_TAX\_REPORT](https://developer-docs.amazon.com/sp-api/docs/report-type-values-tax) * [Settlement Report](https://developer-docs.amazon.com/sp-api/docs/settlement-reports)