amazon-seller-integration

Files (1)

• SKILL.md

SKILL.md (first lines)

# Amazon Seller Central Integration Skill v1.0

> **General reference only.** This skill is general tax/accounting reference material for AI-assisted workflows. It has not been reviewed for any specific person's facts, documents, elections, deadlines, residency, filing status, or local procedures. Do not rely on it to file, pay, amend, or take a tax position without review by a qualified professional in the relevant jurisdiction.

## Section 1 — Platform Overview

Amazon Seller Central is the platform used by third-party sellers on Amazon's marketplace. It handles product listings, order management, fulfilment (FBA or FBM), advertising, and financial settlements. Amazon operates marketplaces in 20+ countries including the US, UK, Germany, France, Italy, Spain, Japan, Australia, India, and Canada.

Amazon's financial data is exceptionally complex because every order generates multiple line items: product price, shipping credits, gift wrap, promotional rebates, FBA fees, referral fees, taxes, and more. Each line item is a separate row in the settlement report.

---

## Section 2 — Export Formats

| Format | Use Case |
|--------|----------|
| TSV (Tab-separated) | Settlement Report V2 (GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2). The primary financial report. |
| CSV | Date Range Reports (custom period exports from Payments dashboard). |
| XML | Settlement Report XML version (legacy). |
| PDF | Summary reports, account activity PDFs (for overview, not line-item data). |

The **Settlement Report V2** is the most important export for bookkeeping. It covers one settlement period (typically 14 days) and includes every financial event. Date Range Reports allow custom period selection but use a slightly different format.

---

## Section 3 — Column Mapping

### Settlement Report V2 (Flat File)

| Column Header | Meaning |
|---------------|---------|
| settlement-id | Unique settlement period identifier. All rows in one settlement share this ID. |
| settlement-start-date | Start of the settlement period (ISO 8601). |
| settlement-end-date | End of the settlement period (ISO 8601). |
| deposit-date | Date Amazon deposited funds to the seller's bank account. |
| total-amount | Total settlement amount deposited. Only populated on the first row. |
| currency | Three-letter ISO currency code (USD, GBP, EUR). |
| transaction-type | Order, Refund, Service Fee, Adjustment, Transfer, Liquidations, other (see Section 4). |
| order-id | Amazon order ID (e.g., 111-1234567-1234567). Blank for non-order transactions. |
| merchant-order-id | Seller's own order reference (if set). |
| adjustment-id | Identifier for adjustment transactions. |
| shipment-id | FBA shipment ID. |
| marketplace-name | Which Amazon marketplace (amazon.com, amazon.co.uk, amazon.de, etc.). |
| amount-type | Category of the amount: ItemPrice, ItemFees, Promotion, ItemWithheldTax, other. |
| amount-description | Specific fee/charge name (see Section 4 for complete list). |
| amount | The monetary value. Positive = credit to seller, negative = debit from seller. |
| fulfillment-id | AFN (Fulfilled by Amazon / FBA) or MFN (Merchant Fulfilled). |
| posted-date | Date the transaction was posted. |
| posted-date-time | Full timestamp of posting (ISO 8601). |
| order-item-code | Amazon's internal line item identifier. |
| merchant-order-item-id | Seller's own line item reference. |
| merchant-adjustment-item-id | Seller's adjustment reference. |
| sku | Product SKU. |
| quantity-purchased | Number of units in the order. |
| promotion-id | Promotion identifier if a promotion was applied. |

---

## Section 4 — Transaction Type Codes

### transaction-type values

| Value | Meaning |
|-------|---------|
| Order | Revenue from a customer order |
| Refund | Refund issued to customer (reverses order amounts) |
| Service Fee | Amazon service charges (subscription, advertising, FBA storage) |
| Adjustment | Manual adjustments (reimbursements, corrections) |
| Transfer | Settlement deposit to seller's bank account |
| Liquidations | FBA liquidation proceeds |
| other | Catch-all for miscellaneous events |

### amount-type values

| Value | Meaning |
|-------|---------|
| ItemPrice | Revenue components: Principal (product price), Shipping, GiftWrap, etc. |
| ItemFees | Amazon fees: Commission (referral fee), FBAPerUnitFulfillmentFee, ShippingHB, etc. |
| Promotion | Promotional discounts funded by the seller |
| ItemWithheldTax | Tax withheld by Amazon on behalf of the seller |
| other | Miscellaneous amounts |

### Key amount-description values

| amount-description | Meaning |
|-------------------|---------|
| Principal | Product sale price (revenue) |
| Shipping | Shipping credit from buyer |
| ShippingTax | Tax on shipping |
| Tax | Product tax collected |
| GiftWrap | Gift wrapping fee |
| Commission | Amazon referral fee (percentage of sale price) |
| FBAPerUnitFulfillmentFee | FBA pick, pack, and ship fee per unit |
| FBAPerOrderFulfillmentFee | FBA per-order fee |
| FBAWeightBasedFee | FBA weight-based shipping fee |
| ShippingHB | Shipping handling fee |
| StorageRenewalBilling | FBA monthly/long-term storage fees |
| Subscription | Professional seller subscription ($39.99/mo) |
| PromotionShipping | Seller-funded free shipping promotion |

---

## Section 5 — Fee Structure

| Fee Type | How It Appears |
|----------|---------------|
| Referral fee (Commission) | transaction-type = Order, amount-type = ItemFees, amount-description = Commission. Typically 8–15% depending on category. Negative amount. |
| FBA fulfilment fee | transaction-type = Order, amount-type = ItemFees, amount-description = FBAPerUnitFulfillmentFee. Per-unit fee based on size/weight. |
| FBA storage fee | transaction-type = Service Fee, amount-description = StorageRenewalBilling. Monthly and long-term storage charges. |
| Professional seller subscription | transaction-type = Service Fee, amount-description = Subscription. $39.99/month. |
| Advertising fees | Separate report (Sponsored Products). Not in the settlement report. |
| Refund administration fee | When Amazon refunds a customer, the original referral fee may be partially retained. Appears as a positive ItemFees amount on the Refund row. |

Multiple fee rows per order are normal. A single order may generate 5–10 rows: Principal, Shipping, Tax, Commission, FBAPerUnitFulfillmentFee, Promotion, etc.

---

## Section 6 — Tax-Relevant Fields

From openaccountants/openaccountants, AGPL-3.0.

More from openaccountants/openaccountants