Restrict item sale by state or zip code

Some items cannot be sold everywhere due to laws, regulations, and your own commercial policies. You should notify Walmart of states where laws, regulations, and ordinances prohibit or restrict your product from being sold. When you set up items for WFS, you can indicate the item sale restrictions if any by its geographic location (state or zip code). The state or zip code is referred to as State Restrictions. You must update the items spec with the required restrictions in the StateRestrictions section by providing the state code or zip code for all the geographic areas where an item cannot be sold.

For example, you can specify restricted item for sale in a state or zip code due to laws preventing sale in that location with StateRestrictionsText set to Illegal for sale. You can also specify any state where you prefer to not have your products sold for commercial reasons by specifying StateRestrictionsText as Commercial.

How restrictions are applied

Restrictions are applied for a product depending on if it is a state restriction or zip code restriction.

  • State restriction - The product will be restricted from being sold anywhere within the specified state.
  • Zip code restriction - The product will be restricted only within the listed 5-digit zip code in a particular state.

IMPORTANT: If you are limiting sales only by zip codes, do not include the state code in that restriction object. If a state code is added to restrictions, sale of the item will be blocked in all zip codes in that state.

Set state restrictions for an item

To set state restrictions during item setup, use the Bulk item setup (Multiple) API with feed type set to feedtype=MP\_WFS\_ITEM.

  1. Provide the state codes for the states where you want to prohibit or restrict the sale of that item.
    For example, to set state restrictions for California and Arkansas, provide states "CA and "AR" in your request payload.
  2. Provide the reason for the restriction. Set StateRestrictionsText to either 'Commercial,' 'Illegal for sale,' or 'None'.

Sample request

This sample request sets commercial restrictions for California and Arkansas, and illegal for-sale restrictions in Texas and Pennsylvania.

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/feeds?feedType=MP_WFS_ITEM' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'WM_QOS.CORRELATION_ID: <uuid>' \ --header 'WM_SEC.ACCESS_TOKEN: <access_token>' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --data '{ "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ { "stateRestrictionsText": "Commercial", "states": "CA,AR" }, { "stateRestrictionsText": "Illegal for sale", "zipCodes": "73301,78701,10001" } ] } ] }'
import requests url = "https://marketplace.walmartapis.com/v3/feeds" headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_QOS.CORRELATION_ID": "<uuid>", "WM_SEC.ACCESS_TOKEN": "<access_token>", "WM_SVC.NAME": "Walmart Service Name",
} params = { "feedType": "MP_WFS_ITEM",
} json_data = { "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ { "stateRestrictionsText": "Commercial", "states": "CA,AR" }, { "stateRestrictionsText": "Illegal for sale", "zipCodes": "73301,78701,10001" } ] } ]
} response = requests.post(url, headers=headers, params=params, json=json_data)
print(response.status_code)
print(response.text)

Modify your code

  • Use a unique WM_QOS.CORRELATION_ID for each request.
  • Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication.

Sample response

The sample response shows the unique ID for the feed submission, which you can use later to check the status of the bulk price update progress.

{ "feedId": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA"
}

Result

If successful, the API response returns a feedID.

You can use this feed ID with the Feed Status API or All Feed Statuses API to monitor the progress of your submission and see the line-item status.

Update state restrictions for an item

To update sales restrictions that you already have set for items, use the Bulk item setup (Multiple) API with feed type set to feedtype=MP\_MAINTENANCE. If you want to change an item's state restrictions, you must override the entire list of state restrictions set during the initial item setup process.

IMPORTANT: Any change to state restrictions overrides the entire list of restrictions that were setup for the SKU during the initial item setup. To update a single restriction, you must provide the complete set of all state restrictions again.

  1. Specify StateRestrictionsText as either 'Commercial,' 'Illegal for sale,' or 'None' for the new restriction, and provide the state code or zip code.
  2. The request payload should include the complete list of state restrictions, as each Bulk item setup API call overrides the previous list of restrictions.

Sample request

This sample request updates the sales restrictions for the specified item. It replaces the full list of restrictions for the SKU.

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/feeds?feedType=MP_MAINTENANCE' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'WM_QOS.CORRELATION_ID: <uuid>' \ --header 'WM_SEC.ACCESS_TOKEN: <access_token>' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --data '{ "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ { "stateRestrictionsText": "Commercial", "zipCodes": "60601,60602" }, { "stateRestrictionsText": "Illegal for sale", "states": "MA" } ] } ] }'
import requests url = "https://marketplace.walmartapis.com/v3/feeds" headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_QOS.CORRELATION_ID": "<uuid>", "WM_SEC.ACCESS_TOKEN": "<access_token>", "WM_SVC.NAME": "Walmart Service Name",
} params = { "feedType": "MP_MAINTENANCE",
} json_data = { "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ {"stateRestrictionsText": "Commercial", "zipCodes": "60601,60602"}, {"stateRestrictionsText": "Illegal for sale", "states": "MA"}, ], } ]
} response = requests.post(url, headers=headers, params=params, json=json_data)
print(response.status_code)
print(response.text)

Sample response

The sample response shows the unique ID for the feed submission, which you can use later to check the status of the bulk price update progress.

{ "feedId": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA"
}

Modify your code

  • Use a unique WM_QOS.CORRELATION_ID for each request.
  • Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication.

Result

If successful, the API response returns a feedID.

You can use this feed ID with the Feed Status API or All Feed Statuses API to monitor the progress of your submission and see the line-item status.

Delete a state restriction

To delete sales restrictions that you already have set for items, use the Bulk item setup (Multiple) API with feed type set to feedtype=MP\_MAINTENANCE.

IMPORTANT: Any change to state restrictions overrides the entire list of restrictions that were setup for the SKU during the initial item setup. To delete a single restriction, you must provide the complete set of all state restrictions again.

  1. Set the state restrictions attribute to None in the payload request. You do not need to specify the state code or zip code. For example, set stateRestrictionsText: None.
  2. In the request payload, provide a complete list of state restrictions for all the restrictions you want to keep. Each Bulk item setup API call overrides the previous list of restrictions.

Sample request

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/feeds?feedType=MP_MAINTENANCE' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'WM_QOS.CORRELATION_ID: <uuid>' \ --header 'WM_SEC.ACCESS_TOKEN: <access_token>' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --data '{ "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ { "stateRestrictionsText": "Commercial", "states": "CA" } ] } ] }'
import requests url = "https://marketplace.walmartapis.com/v3/feeds" headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_QOS.CORRELATION_ID": "<uuid>", "WM_SEC.ACCESS_TOKEN": "<access_token>", "WM_SVC.NAME": "Walmart Service Name",
} params = { "feedType": "MP_MAINTENANCE",
} json_data = { "items": [ { "sku": "JE-ICF1-TR6P", "stateRestrictions": [ {"stateRestrictionsText": "Commercial", "states": "CA"} ], } ]
} response = requests.post(url, headers=headers, params=params, json=json_data)
print(response.status_code)
print(response.text)

Modify your code

  • Use a unique WM_QOS.CORRELATION_ID for each request.
  • Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication.

Sample response

The sample response shows the unique ID for the feed submission, which you can use later to check the status of the bulk price update progress.

{ "feedId": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA"
}

Result

If successful, the API response returns a feedID.

You can use this feed ID with the Feed Status API or All Feed Statuses API to monitor the progress of your submission and see the line-item status.

List of state codes

The following table lists the U.S. 2-letter state codes. You can use the state code in thestates field.

State NameState CodeState NameState Code
AlabamaALNew MexicoNM
AlaskaAKNew YorkNY
ArizonaAZNorth CarolinaNC
ArkansasARNorth DakotaND
CaliforniaCAOhioOH
ColoradoCOOklahomaOK
ConnecticutCTOregonOR
DelawareDEPennsylvaniaPA
FloridaFLRhode IslandRI
GeorgiaGASouth CarolinaSC
HawaiiHISouth DakotaSD
IdahoIDTennesseeTN
IllinoisILTexasTX
IndianaINUtahUT
IowaIAVermontVT
KansasKSVirginiaVA
KentuckyKYWashingtonWA
LouisianaLAWest VirginiaWV
MichiganMIWisconsinWI
MaineMNWyomingWY
MississippiMSDistrict of ColumbiaDC
MissouriMOAmerican SamoaAS
MontanaMTFederated States of MicronesiaFM
NebraskaNEGuamGU
NevadaNVMarshall IslandsMH
New HampshireNHNorthern Mariana IslandsMP
New JerseyNJPuerto RicoPR
PalauPWVirgin IslandsVI