# listings_build_payload (https://sellersheetai.com/docs/mcp-api/tools/listings_build_payload)

> Build Amazon-shaped attribute JSON from a Publish Queue row's flat cells, per SKU, driven by the productType schema.

Access: **READ** · toolset amazon_sp · family 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

MCP tool call:

```json
{
  "name": "listings_build_payload",
  "arguments": {
    "store": "myStore-US",
    "productType": "<productType>",
    "rows": []
  }
}
```

Tool API (early access — contact us):

```bash
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":[]}'
```

## Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `store` | string | yes | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
| `productType` | string | yes | the one productType whose schema shapes every row (a row's own productType is ignored — call once per productType), e.g. "HEADPHONES". |
| `rows` | object[] | yes | [{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. 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. |
| `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

- `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 | PARENT

## Gotchas

- 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.