African Delights® US Ecommerce
Data Source
This page documents the Amazon source feeding the dashboard, the filters currently applied, and the QuickBooks-oriented account definitions used by the dashboard when building the monthly output.
Amazon Data Sources — Architecture
Amazon data enters the dashboard through two separate APIs with different scopes and purposes. They must not be confused.
SP-API Finance Transactions
Used by: Main Profitability Dashboard
Settlement-based data — reflects exactly what Amazon deposits into the bank account. Reports advertising as an account-level total for the period, not broken out by product. Source of truth for P&L, journal entries, and cash reconciliation.
Amazon Advertising API
Used by: Product-Level P&L · Pricing Tool
Disaggregated ad spend by ASIN/campaign. Required for per-product profitability and accurate advertising cost-per-unit in the pricing calculator. Uses a separate LWA Security Profile with the advertising::campaign_management scope.
SP-API Source Report
System pulled
Amazon Selling Partner API Finances Transactions feed, requested by posted date range from the North America endpoint.
Endpoint
GET /finances/2024-06-19/transactions on sellingpartnerapi-na.amazon.com.
Marketplace filter
The app uses all marketplace IDs listed in MARKETPLACE_IDS from .env.local and aggregates them into one accounting output.
Date fields
The date picker values are sent as postedAfter and postedBefore. The dashboard is intentionally based on posted date, not order date.
Transaction filter
The current code requests only transactions where transactionStatus = RELEASED.
Manual Verification
- 1. Open the dashboard and note the exact start date and end date you used.
- 2. Pull Amazon finances or statement data for the same posted date range.
- 3. Use the same marketplace scope as the MARKETPLACE_IDS configured in the app.
- 4. Keep released transactions aligned with the same scope the API is using.
- 5. Compare the resulting QuickBooks account totals and validation warnings rather than expecting a line-for-line Amazon Summary replica.
Amazon Advertising API — Configuration
System pulled
Amazon Advertising API (separate from SP-API). Uses a dedicated LWA Security Profile with the advertising::campaign_management scope.
Credentials
AMAZON_ADVERTISING_CLIENT_ID and AMAZON_ADVERTISING_CLIENT_SECRET in .env.local. These are different from the SP-API LWA credentials and must not be mixed.
Where used
Product-level P&L view and Pricing Tool only. The main Profitability Dashboard uses SP-API settlement data exclusively because it reflects actual bank account deposits.
Why separate
SP-API finance transactions report advertising spend as an account-level total (not per ASIN). The Advertising API disaggregates spend by campaign and ASIN, enabling per-product profitability and accurate COGS in the pricing calculator.
Auth flow
OAuth 2.0 Authorization Code Grant. Connect via the Amazon Advertising card in the Amazon diagnostic panel on the main dashboard. Tokens stored in data/amazon-ads-auth.json.
Redirect URI
https://labels.africandelightstore.com/amazon-ads/redirect (registered in LWA Security Profile). Set AMAZON_ADS_REDIRECT_URL in .env.local to override.
SP-API Variables Used In The Pull
| Variable | Source | Definition |
|---|---|---|
| startDate | Dashboard date picker | Sent to Amazon as postedAfter after conversion to ISO timestamp. |
| endDate | Dashboard date picker | Sent to Amazon as postedBefore after conversion to ISO timestamp. |
| marketplaceIds | .env.local -> MARKETPLACE_IDS | All marketplace IDs in the comma-separated list are pulled and aggregated together. |
| transactionStatus | Hard-coded in API request | Always set to RELEASED in the current implementation. |
| breakdown.breakdownType | Amazon transaction breakdown payload | Primary driver for the QuickBooks account mapping logic. |
| transaction.description | Amazon transaction payload | Fallback context for mapping when breakdownType alone is not sufficient. |
| breakdown.breakdownAmount.currencyAmount | Amazon transaction breakdown payload | The numeric amount summed into the final account_name output. |
| transaction.totalAmount.currencyCode | Amazon transaction payload | Used to set the dashboard currency display, usually USD. |
QuickBooks Account Definitions
These are the account-level output lines the dashboard currently generates from the Amazon transactions. They are intentionally designed for journal-entry and profitability use, not as a replica of Amazon's native statement sections.
| Account name | Category | FBA flag | Definition |
|---|---|---|---|
| Product sales (non-FBA) | Income | FBM | Amazon unified summary income line for non-FBA product sales. |
| Product sale refunds (non-FBA) | Contra Revenue | FBM | Amazon unified summary income line for refunded non-FBA product sales. |
| FBA product sales | Income | FBA | Amazon unified summary income line for FBA product sales. |
| FBA product sale refunds | Contra Revenue | FBA | Amazon unified summary income line for refunded FBA product sales. |
| FBA inventory credit | Income | FBA | Amazon unified summary income line for FBA inventory credits. |
| FBA liquidation proceeds | Income | FBA | Amazon unified summary income line for liquidation proceeds. |
| FBA Liquidations proceeds adjustments | Income | FBA | Amazon unified summary income line for liquidation adjustments. |
| Shipping credits | Income | N/A | Amazon unified summary income line for shipping credits. |
| Shipping credit refunds | Contra Revenue | N/A | Amazon unified summary income line for shipping credit refunds. |
| Gift wrap credits | Income | N/A | Amazon unified summary income line for gift wrap credits. |
| Gift wrap credit refunds | Contra Revenue | N/A | Amazon unified summary income line for gift wrap credit refunds. |
| Promotional rebates | Contra Revenue | N/A | Amazon unified summary income line for promotional rebates. |
| Promotional rebate refunds | Contra Revenue | N/A | Amazon unified summary income line for promotional rebate refunds. |
| A-to-z Guarantee claims | Contra Revenue | N/A | Amazon unified summary income line for A-to-z Guarantee claims. |
| Chargebacks | Contra Revenue | N/A | Amazon unified summary income line for chargebacks. |
| Amazon Shipping Reimbursement Adjustments | Income | N/A | Amazon unified summary income line for shipping reimbursement adjustments. |
| SAFE-T reimbursement | Income | N/A | Amazon unified summary income line for SAFE-T reimbursement. |
| Seller fulfilled selling fees | Expense | FBM | Amazon unified summary expense line for seller fulfilled selling fees. |
| FBA selling fees | Expense | FBA | Amazon unified summary expense line for FBA selling fees. |
| Selling fee refunds | Expense | N/A | Amazon unified summary expense line for selling fee refunds. |
| FBA transaction fees | Expense | FBA | Amazon unified summary expense line for FBA transaction fees. |
| FBA transaction fee refunds | Expense | FBA | Amazon unified summary expense line for FBA transaction fee refunds. |
| Other transaction fees | Expense | N/A | Amazon unified summary expense line for other transaction fees. |
| Other transaction fee refunds | Expense | N/A | Amazon unified summary expense line for other transaction fee refunds. |
| FBA inventory and inbound services fees | Expense | FBA | Amazon unified summary expense line for FBA inventory and inbound services fees. |
| Shipping label purchases | Expense | FBM | Amazon unified summary expense line for shipping label purchases. |
| Shipping label refunds | Expense | FBM | Amazon unified summary expense line for shipping label refunds. |
| Carrier shipping label adjustments | Expense | FBM | Amazon unified summary expense line for carrier shipping label adjustments. |
| Service fees | Expense | FBA | Amazon unified summary expense line for service fees. |
| Refund administration fees | Expense | N/A | Amazon unified summary expense line for refund administration fees. |
| Adjustments | Expense | N/A | Amazon unified summary expense line for adjustments. |
| Cost of Advertising | Expense | N/A | Amazon unified summary expense line for cost of advertising. |
| Refund for Advertiser | Expense | N/A | Amazon unified summary expense line for refund for advertiser. |
| Liquidations fees | Expense | FBA | Amazon unified summary expense line for liquidations fees. |
| Receivables Deductions | Expense | N/A | Amazon unified summary expense line for receivables deductions. |
| Amazon Shipping Charge Adjustments | Expense | N/A | Amazon unified summary expense line for Amazon shipping charge adjustments. |
| Product, shipping, gift wrap taxes and regulatory fee collected | Tax | N/A | Amazon unified summary tax line for collected taxes and regulatory fees. |
| Product, shipping, gift wrap taxes and regulatory fee refunded | Tax | N/A | Amazon unified summary tax line for refunded taxes and regulatory fees. |
| Amazon Obligated Tax and Regulatory Fee Withheld | Tax | N/A | Amazon unified summary tax line for obligated tax and regulatory fee withheld. |
| Transfers to bank account | Transfer | N/A | Amazon unified summary transfer line for bank disbursements. |
| Failed transfers to bank account | Transfer | N/A | Amazon unified summary transfer line for failed bank transfers. |
| Disburse to Amazon Gift Card balance | Transfer | N/A | Amazon unified summary transfer line for gift card balance disbursements. |
| Charges to credit card and other debt recovery | Transfer | N/A | Amazon unified summary transfer line for debt recovery and card charges. |
| Walmart product sales (WFS) | Income | FBA | Walmart settlement gross sales revenue for WFS orders. |
| Walmart product sales (Seller Fulfilled) | Income | FBM | Walmart settlement gross sales revenue for seller-fulfilled orders. |
| Walmart product sale refunds (WFS) | Contra Revenue | FBA | Walmart settlement refunded retail sales for WFS orders. |
| Walmart product sale refunds (Seller Fulfilled) | Contra Revenue | FBM | Walmart settlement refunded retail sales for seller-fulfilled orders. |
| Walmart funded savings | Contra Revenue | N/A | Walmart-funded promotional discounts deducted from gross sales. |
| Walmart referral fees (WFS) | Expense | FBA | Walmart commission on WFS sales and refunds. |
| Walmart referral fees (Seller Fulfilled) | Expense | FBM | Walmart commission on seller-fulfilled sales and refunds. |
| Walmart WFS fulfillment fees | Expense | FBA | Walmart WFS per-unit fulfillment fees (adjustment code 5041). |
| Walmart WFS return processing fees | Expense | FBA | Walmart WFS return processing fees (adjustment code 5075). |
| Walmart shipping label charges | Expense | FBM | Walmart shipping label service charges for seller-fulfilled orders (5046). |
| Walmart shipping label refunds | Expense | FBM | Refunds for unused Walmart shipping labels (adjustment code 5055). |
| Walmart return shipping charges | Expense | FBM | Walmart return shipping charges for seller-fulfilled orders (5013). |
| Walmart shipping revenue | Income | FBM | Net shipping revenue from customers on seller-fulfilled Walmart orders. |
| Walmart gift wrap revenue | Income | FBM | Net gift wrap revenue on Walmart orders. |
| Walmart WFS storage fees | Expense | FBA | Walmart WFS storage and other fee charges (adjustment code 5073). |
| Walmart other fee revenue | Income | N/A | Walmart settlement 'Net Fee Revenue' on SALE and REFUNDED rows (miscellaneous fees collected or refunded). |
| Walmart taxes collected | Tax | N/A | Sales tax collected by Walmart on behalf of seller. |
| Walmart taxes refunded | Tax | N/A | Sales tax refunded on returned Walmart orders. |
| Walmart net disbursement | Transfer | N/A | Net settlement amount disbursed from Walmart to seller bank account. |
| Shopify product sales | Income | FBM | Shopify order subtotal revenue from online store orders. |
| Shopify product sale refunds | Contra Revenue | FBM | Refunded Shopify order subtotal amounts. |
| Shopify shipping income | Income | FBM | Shipping charged to customers on Shopify orders. |
| Shopify selling fees | Expense | N/A | Placeholder for Shopify payment processing and app fees until payout data is wired. |
| Shopify taxes collected | Tax | N/A | Sales tax collected on Shopify orders. |
| TikTok product sales | Income | FBM | TikTok Shop order revenue (best-effort from Open API order payloads). |
| TikTok product sale refunds | Contra Revenue | FBM | TikTok Shop refunded or cancelled order amounts (best-effort). |
| TikTok shipping income | Income | FBM | TikTok Shop shipping revenue charged to customers (best-effort). |
| TikTok selling fees | Expense | N/A | TikTok Shop platform/commission fees (placeholder until finance endpoints are wired). |
| TikTok taxes collected | Tax | N/A | Sales tax collected on TikTok Shop orders (best-effort). |
Current mapped account lines in code: 72