listings_build_payload
Build Amazon-shaped attribute JSON from a Publish Queue row's flat cells, per SKU, driven by the productType schema.
readAmazon Seller (SP-API)sp.definitionsProductTypes_2020-09-01
Pre-flight only — nothing is submitted; show data.warnings to the user, then listings_submit_items. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType}
Call it
In an AI client (MCP)
{
"name": "listings_build_payload",
"arguments": {
"store": "myStore-US",
"productType": "<productType>",
"rows": []
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/listings_build_payload \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US","productType":"<productType>","rows":[]}'Early access — the Tool API is open on request, contact us.
Arguments
| Name | Type | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
productTyperequired | string | the one productType whose schema shapes every row (a row's own productType is ignored — call once per productType), e.g. "HEADPHONES". |
rowsrequired | object[] | [{sku, attributes: {key: cell_value}}]. A key is Amazon's own flat-file key, copied verbatim from a listings_prepare_publish_queue_template column — never built by hand: `<attr>[<sel>=<v>]…#<n>.<field>…`, where #n is a 1-based entry, .field an object field, and the bracket selectors are only marketplace_id / language_tag (written as the placeholder tokens marketplace_id / language_tag, filled from store and language_tag) and audience (ALL | B2B). Every other selector (currency, type, size_system, fulfillment_channel_code …) is an ordinary key with its value in the cell. `#*` is the one-cell form of a multi-value attribute (bullet_point, warranty_description): one value per line. Values: text as a string, numbers as "1.5" or 1.5, booleans as true/false/yes/no. Examples: "item_name[marketplace_id=marketplace_id][language_tag=language_tag]#1.value": "Earbuds" "item_weight[marketplace_id=marketplace_id]#1.value": "1.5", "…#1.unit": "kilograms" "externally_assigned_product_identifier[marketplace_id=marketplace_id]#1.value": "123456789012", "…#1.type": "upc" "purchasable_offer[marketplace_id=marketplace_id][audience=ALL]#1.our_price#1.schedule#1.value_with_tax": "19.99" |
locale | string | schema locale for localized labels (a getDefinitionsProductType locale, e.g. en_US); defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW.DEFAULTarar_AEdede_DEenen_AEen_AUen_CAen_GBen_INen_SGen_USeses_ESes_MXes_USfrfr_CAfr_FRitit_ITjaja_JPnlnl_NLplpl_PLptpt_BRpt_PTsvsv_SEtrtr_TRzhzh_CNzh_TW |
language_tag | string | fills the language_tag token; defaults to the marketplace's primary listing locale (US en_US, UK en_GB, DE de_DE, AE/SA en_AE) — pass one only to list in another language the marketplace supports. |
Result
Every tool answers {notification, data, human_action}; data carries:
data.rows— [{sku, attributes, warnings, productType, requirements}] — requirements is the set carried into the PUT: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY. data.total_attrs, data.warnings_count: show the warnings before submitting.
Params (Amazon schema)
productType*: string
sellerId: string
marketplaceIds*: [string]
productTypeVersion: string
requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY
requirementsEnforced: ENFORCED | NOT_ENFORCED
locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)
parentageLevel: NONE | CHILD | PARENTGotchas
- Nothing is filled in for you: what you write is what is sent — a blank unit ships with no unit and Amazon's issues[] names what is missing; the placeholder tokens are the only thing resolved. Hidden fields (list_price[…]#1.currency, child_parent_sku_relationship#1.child_relationship_type = "variation" on parent and child) are ordinary keys. A filled key that does not parse, or names a field this productType's schema lacks (a pre-v6 pseudo key such as …#1.b2b_quantity_discount), comes back in that row's warnings as retired_column_layout, and listings_submit_items / listings_submit_feed skip the row — re-run listings_prepare_publish_queue_template. Dates are UTC on this path: an instant "2026-09-19T10:00:00Z" or "YYYY-MM-DD" (a sale start = 00:00:00Z, a sale end = 23:59:59Z); never a slash date. A sheet's sale cells are the seller's local time — convert before calling. product_site_launch_date comes back from the fetch tools and is sent like any key; once a product has sold, the date shoppers see cannot change — on an existing listing remove the key or leave the fetched value.