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
.
- 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. - 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.
- Specify
StateRestrictionsText
as either 'Commercial,' 'Illegal for sale,' or 'None' for the new restriction, and provide the state code or zip code. - 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.
- 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, setstateRestrictionsText: None
. - 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 Name | State Code | State Name | State Code |
---|---|---|---|
Alabama | AL | New Mexico | NM |
Alaska | AK | New York | NY |
Arizona | AZ | North Carolina | NC |
Arkansas | AR | North Dakota | ND |
California | CA | Ohio | OH |
Colorado | CO | Oklahoma | OK |
Connecticut | CT | Oregon | OR |
Delaware | DE | Pennsylvania | PA |
Florida | FL | Rhode Island | RI |
Georgia | GA | South Carolina | SC |
Hawaii | HI | South Dakota | SD |
Idaho | ID | Tennessee | TN |
Illinois | IL | Texas | TX |
Indiana | IN | Utah | UT |
Iowa | IA | Vermont | VT |
Kansas | KS | Virginia | VA |
Kentucky | KY | Washington | WA |
Louisiana | LA | West Virginia | WV |
Michigan | MI | Wisconsin | WI |
Maine | MN | Wyoming | WY |
Mississippi | MS | District of Columbia | DC |
Missouri | MO | American Samoa | AS |
Montana | MT | Federated States of Micronesia | FM |
Nebraska | NE | Guam | GU |
Nevada | NV | Marshall Islands | MH |
New Hampshire | NH | Northern Mariana Islands | MP |
New Jersey | NJ | Puerto Rico | PR |
Palau | PW | Virgin Islands | VI |
Updated 6 days ago