Amazon Product Type Schema Quirks: Requirement vs Visibility vs Conditional Logic

[Quankzx]

Question: How to match Seller Central's "Optional" logic using SP-API Schemas?

I'm struggling to get my 3rd party listing UI to mirror Seller Central 100%. Specifically, I'm seeing a major conflict in field requirements:

The Conflict: league_name & team_name

• SP-API Metadata: Root is "IsRequired": false, but nested properties.value is "IsRequired": true.
• Seller Central UI: These fields appear correctly as Optional/Option (no red star).
• My Engine: Currently marks them as Required because it sees the nested value.IsRequired: true.

The Question:
What is the "Golden Rule" to decide if a field gets a Red Star? Does Amazon ignore ALL nested requirements when rendering the initial form, only checking IsRequired at the Root Attribute level?

Parity Checklist:

How do we determine these 3 states to match Amazon exactly?

1. Hidden: Field is not rendered.
2. Optional (Option): Field is visible but no red star.
3. Required: Field is visible with a red star.

Is there a specific logic/vocabulary in the JSON schema that controls this "Optional by default" behavior for attributes like Sports fields in a Beauty category?

Marketplace/PT: US / TEMPORARY_TATTOO

[weilinggu]

Hi @Quankzx

SP-API Metadata: Root is "IsRequired": false, but nested properties.value is "IsRequired": true.
What this means is that for attribute league_name, either you do not provide this attribute at all in your product data, or else if you do provide it, you have to provide value within it.

To provide some examples:

Having no league_name at all is fine. Example payload:

{
...
       "product_description": [
            {
                "marketplace_id": "ATVPDKIKX0DER",
                "language_tag": "en_US",
                "value": "Example Shop Direct Product description"
            }
        ],
        "brand": [
            {
                "marketplace_id": "ATVPDKIKX0DER",
                "language_tag": "en_US",
                "value": "Example brand"
            }
        ],
...
}

Provide league_name but include value is fine. Example payload:

{
...
       "product_description": [
            {
                "marketplace_id": "ATVPDKIKX0DER",
                "language_tag": "en_US",
                "value": "Example Shop Direct Product description"
            }
        ],
        "league_name": [
            {
                "language_tag": "en_US",
                "value": "Example league"
            }
        ],
        "brand": [
            {
                "marketplace_id": "ATVPDKIKX0DER",
                "language_tag": "en_US",
                "value": "Example brand"
            }
        ],
...
}

But providing league_name without value would not work. Example payload:

{
...
        "league_name": [
            {
                "language_tag": "en_US"
            }
        ],
...
}

Thanks
Weiling
Amazon Selling Partner Services

[Quankzx]

Thank you @weilinggu , I’ve resolved this issue. The final problem I’m facing is customizing this product type. As shown in the image, the attributes listed in this tab do not seem to appear in the sample JSON returned for the product type. What should I do in this case?

If this is a customization that I designed myself, what identifiers should be used for these attributes when sending them to the listing API?

[weilinggu]

Customization is not a functionality we support via the API right now. At this moment, you can create a base listing via the SP-API and configure customization in Seller Central. I will share the feedback of wanting to handle this via the API back to the team.

Thanks
Weiling
Amazon Selling Partner Services

[ThetaRgo]

Hi，Is the customized interface API available now? thanks

[Muawiya-contact]

Re: Customization Tab Attributes & the Listings API

Good question, and I can see exactly what you're looking at in that screenshot.

That Customizations tab — with your surfaces, closure types, item shapes, colors, and dropdowns — is part of Amazon Custom, which is a separate program layered on top of the standard listing. And that's exactly why those fields don't appear in the product type JSON schema: they're not standard listing attributes at all.

---

Why They're Not in the Schema

The fields you see in that tab (Surface, Closure Type, Item Shape, Color, Option Dropdown, etc.) are Amazon Custom configuration, not product type attributes. They live in a completely different system — the Amazon Custom API — not the Listings Items API.

So you won't find them by digging through the product type schema. They simply aren't there.

---

The Right API for This

Amazon has a dedicated Customization API for exactly this:

PUT /aplus/2020-11-01/listings/{asin}/customizationInfo

⚠️ This is part of the A+ Content / Amazon Custom API surface, not the standard Listings API.

With it you can programmatically manage:

• Surfaces (Surface 1, Surface 2, etc.)
• Customization options (Closure Type, Item Shape, Color, Dropdowns)
• Preview images and clipping masks
• "Make this required for buyers" flag (that checkbox you see on Special Feature and Option Dropdown)

---

What the Identifiers Look Like

Since you asked — when sending customization options, you define them yourself. Amazon doesn't prescribe field names for custom options. A rough structure looks like:

{
  "surfaces": [
    {
      "label": "Surface 1",
      "customizationOptions": [
        {
          "label": "Closure Type",
          "type": "selection",
          "isRequired": false,
          "options": [
            { "label": "Option 1" },
            { "label": "Option 2" }
          ]
        },
        {
          "label": "Special Feature",
          "type": "selection",
          "isRequired": true
        }
      ]
    }
  ]
}

The label values are what you define — they map to what buyers see in the "Customize Now" window.

---

Quick Summary

What you see in the tab	Where it comes from
Product Identity, Description, Offer tabs	Listings Items API + product type schema
Customizations tab	Amazon Custom API — separate system
Field names / identifiers	You define them yourself
"Make required for buyers"	isRequired flag in Custom API payload

---

Practical Next Step

Check the Amazon Custom API docs here:
👉 https://developer-docs.amazon.com/amazon-shipping/docs/amazon-custom-api-use-case-guide

If you're already enrolled in Amazon Custom (your screenshot confirms you are — it says "You are registered for Amazon Custom"), you should have access to this API endpoint under your SP-API app.

Hope that clears up why the schema search was coming up empty — you were looking in the right repo, just the wrong drawer. 🙂

[Quankzx]

First of all, thank you very much for sharing your insights on my issue. However, it seems that the documentation for A+ Content / Amazon Custom API does not mention the API PUT /aplus/2020-11-01/listings/{asin}/customizationInfo. Even the documentation link you provided does not appear to exist. Could you please clarify and provide more details about this process?