Collectibles item setup and maintenance

Use the Item Management APIs to set up collectible items with accurate listing attributes that improve item discoverability and the customer experience.

Overview

The Walmart Collectibles program supports two product type models:

• Collectible-only product types: All items submitted under these product types are treated as Collectibles.
• Product types that support Standard and Collectible items: Approved sellers can identify eligible items as Collectibles by submitting item_assortment_type as Collectible.

Program eligibility

To list collectible items, sellers must be approved for the Collectibles program by Walmart. Sellers who are not approved cannot set up collectible items, edit existing collectible listings, or submit collectible-specific attributes.

To request access:

1. Contact your account manager for an invitation.
2. In Seller Center, open Growth.
3. Select Exclusive Programs.
4. Click Apply.

Supported product types

Item setup

Set up an item in a collectible-only product type

1. Select a supported collectible-only product type.
2. Retrieve the latest item specification.
3. Do not submit item_assortment_type.
4. Submit collectible_grading_type.
5. For New or Ungraded items, submit condition. For Graded items, submit grading_company and collectible_grade.
6. Submit all other required and conditionally required attributes returned in the item specification.
7. Submit the item.

Set up a collectible in a product type that supports Standard and Collectible items

1. Select an eligible product type.
2. Retrieve the latest item specification.
3. Set item_assortment_type to Collectible.
4. Submit collectible_grading_type.
5. For New or Ungraded items, submit condition. For Graded items, submit grading_company and collectible_grade.
6. Submit blind_box when it is included in the item specification for the selected product type.
7. Submit all other required and conditionally required attributes returned in the item specification.
8. Submit the item.

Note: If item_assortment_type is Standard or omitted, Walmart treats the item as non-collectible. Do not submit collectible-specific attributes.

Item maintenance

Maintain a collectible item

1. Retrieve the item.
2. Update only supported mutable attributes.
3. Do not change condition, collectible_grading_type, grading_company, or collectible_grade.
4. For product types that support both Standard and Collectible items, do not change item_assortment_type.
5. Create a new item when an immutable collectible attribute or the assortment type must change.

Offer Setup by Match

Collectible attributes for eligible product types are available in the Offer Setup by Match specification. Approved Collectibles sellers can create collectible offers by matching to an existing item.

WFS support

Collectible attribute reference

item_assortment_type

Migration note: item_assortment_type is the new attribute used to identify whether an item is Standard or Collectible. Integrations should begin using item_assortment_type instead of isCollectible. isCollectible may still be present in some existing flows during the transition.

collectible_grading_type

condition

Condition guidance

Graded Coins: Walmart derives condition from grading_company and collectible_grade. Do not submit condition.

The item specification may include a consolidated list of condition values. Submit only a value supported for the selected collectible_grading_type and product type.

grading_company

Approved grading companies vary by product type.

collectible_grade

The submitted collectible_grade must match a value supported for the selected grading_company and product type. Use the latest item specification for the allowed combinations.

blind_box

The blind_box attribute applies to 7 of the 20 product types that support Standard and Collectible items. It does not apply to collectible-only product types.

Validation rules

Standard items and items with item_assortment_type omitted may still require standard item attributes, including condition. The table lists only collectible-specific requirements.

Product-type-specific attributes

Additional collectible attributes vary by product type. Refer to the latest item specification to determine which attributes are supported and whether they are required, conditionally required, recommended, or optional.

Error handling

For HTTP status codes and general API error definitions, refer to the Error codes guide.

Collectible-only product type schema excerpt

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "MPItemFeed", "type": "object", "description": "Defines an item feed submission that includes collectible item attributes.", "properties": { "MPItemFeedHeader": { "type": "object", "description": "Contains attributes that apply to the entire submission. Include this object once for all items in the feed." }, "MPItem": { "type": "array", "minItems": 1, "description": "Contains each item included in the submission. Add one array entry for each unique item configuration.", "items": { "type": "object", "properties": { "Visible": { "type": "object", "properties": { "Collectible Ephemera": { "type": "object", "description": "Contains attributes for the Collectible Ephemera product type. The collectible_grading_type attribute is required. Additional requirements depend on the selected grading type.", "properties": { "collectible_grading_type": { "type": "string", "description": "Indicates whether the collectible is new, ungraded, or professionally graded. Allowed values: Graded, New, Ungraded.", "enum": [ "Graded", "New", "Ungraded" ] }, "condition": { "type": "string", "description": "Describes the physical state of a new or ungraded collectible. Submit a value supported by the latest item specification." }, "grading_company": { "type": "string", "description": "Identifies the third-party organization that graded the collectible. Submit a value supported by the latest item specification." }, "collectible_grade": { "type": "string", "description": "Identifies the grade assigned by the selected grading company. Submit a value supported by the latest item specification." } }, "required": [ "collectible_grading_type" ], "allOf": [ { "if": { "properties": { "collectible_grading_type": { "const": "Graded" } }, "required": [ "collectible_grading_type" ] }, "then": { "required": [ "grading_company", "collectible_grade" ] } }, { "if": { "properties": { "collectible_grading_type": { "enum": [ "New", "Ungraded" ] } }, "required": [ "collectible_grading_type" ] }, "then": { "required": [ "condition" ] } } ], "additionalProperties": true } }, "required": [ "Collectible Ephemera" ] } }, "required": [ "Visible" ] } } }, "required": [ "MPItemFeedHeader", "MPItem" ]
}

Standard and Collectible product type schema excerpt

A completely generic example for a product type that supports Standard and Collectible items cannot be submission-ready because the product type name and many required attributes vary by specification. The following illustrative payload pattern uses placeholders to show the collectible structure for an eligible product type.

{ "MPItemFeedHeader": { "businessUnit": "WALMART_US", "locale": "en", "version": "<latest specification version>" }, "MPItem": [ { "Visible": { "<supported product type>": { "item_assortment_type": "Collectible", "productName": "<product name>", "brand": "<brand name>", "collectible_grading_type": "Ungraded", "condition": "<supported ungraded condition>", "shortDescription": "<product description>", "keyFeatures": [ "<key feature 1>", "<key feature 2>", "<key feature 3>" ], "mainImageUrl": "https://example.com/images/<image-file>.jpg", "isProp65WarningRequired": "No", "ageGroup": [ "<supported age group>" ], "assembledProductHeight": { "unit": "in", "measure": 0 }, "assembledProductWidth": { "unit": "in", "measure": 0 }, "color": "<color>", "has_written_warranty": "No", "material": [ "<material>" ], "maximumRecommendedAge": { "unit": "years", "measure": 99 }, "minimumRecommendedAge": { "unit": "years", "measure": 0 }, "netContent": { "productNetContentUnit": "Each", "productNetContentMeasure": 1 }, "smallPartsWarnings": [ "0 - No warning applicable" ], "blind_box": "No" } }, "Orderable": { "sku": "<seller SKU>", "productIdentifiers": { "productId": "<product identifier>", "productIdType": "GTIN" }, "price": 0.00, "ShippingWeight": 0, "country_of_origin_substantial_transformation": "<country of origin>" } } ]
}

Usage notes

• Replace <supported product type> with the exact product type returned in the specification.
• Set item_assortment_type to Collectible.
• Allowed collectible_grading_type values: New, Ungraded, Graded.
• For New or Ungraded, submit a supported condition.
• For Graded, replace condition with:

"grading_company": "<supported grading company>",
"collectible_grade": "<supported grade>"

• Include blind_box only when it appears in the selected product type specification. Allowed values in the supplied engineering specifications: No, Yes.
• Add every other required or conditionally required field returned for the selected product type.
• Placeholder values such as 0, <product name>, and <seller SKU> are documentation placeholders and must be replaced before submission.