Interactive API Console

Test Macy's API using our easy to use Interactive Console! You can also view more detailed written documentation. (Note: You must attain approval for an API key for one of the services in the drop-down menu below before being able to use the Macy's API Console.)

Please contact us if you are having trouble getting access to keys: Click Here

Ad Media Services

Catalog Services give you access to the Macy's product line in a variety of ways:

Bag Services

Promotion & Coupon Services

Registry Services

Store Services give you access to the Macy's store information including in store availability of products:

OAuth 2.0 Flow:

Existing Client Credentials:

API Key:

App/Key: Manually provide key information

Shared Secret:

Client ID:

Client Secret:

Client ID:

Client Secret:

Username:

Password:

Client ID:

Client Secret:

Authorization Code:

Access Token:

Username:

Password:

Username:

Binary Security Token:

Username:

Password:

Ad Media Services

List Methods

Expand Methods

GET Category Ad Media v2/admedia/category

This service allows you to retrieve ad media specific to a product category ID. Please click here for the static documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON.
categoryId	string	Specify one or more category Id's separated by comma. (Required) Ex. 27058
channel	string	Channel can be either SITE, REGISTRY (Required) Ex. SITE
secure	string	By default this is set to false. If set to true links in response will be https NOT http. (Optional) Ex. true
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Global Ad Media :version/admedia/global

This service allows you to retrieve global ad media, that is Ad's that are not for a specific Product Category ID. You must know what the Media Pool Name of the Ad is to retrieve the Ad using this call. Please click here for the static documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:version	string	API Version (New customers should use v3)(Required) Ex. v3
poolName	string	Media Pool Name. Specify one or more pool names separated by comma Ex. GLOBALFOOTER,ABOVE_NAV_POOL.(Required) Ex. GLOBALFOOTER
secure	string	By default this is set to false. If set to true links in response will be https NOT http (Optional) Ex. true
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.(Optional) Ex. magicofmacysapi

Catalog Services

List Methods

Expand Methods

GET Category Index v3/catalog/category/index

This API provides an option to obtain all the categoryIDs in a hierarchical structure by making a call with the âindexâ parameter. Then you can use the CategoryBrowse call (Below) to make subsequent calls to get the more detailed category info. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
category	string	Use this parameter to narrow the response returned by category ID. (Optional) Ex. 118
depth	string	Number between 1-5. This allows you to return additional layers of subcategories. (Optional) Ex. 2
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.(Optional) Ex. magicofmacysapi

GET Category Browse v3/catalog/category/:categoryId

The CategoryBrowse service can retrieve information on the hierarchy of product categories as on Macys.com. In addition to the hierarchy details such as category description, Product IDs within the category & facets that can appear for those products can be retrieved.The API enables users to obtain category details by specifying a category ID. All of these category ID's can be pulled from the CategoryIndex call (above). Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:categoryId	int	Multiple Category ID's can be sent by seperating them by Comma's: Maximum of 250 (Optional). Ex. 118
show	string	Every show parameter specified would enable users to restrict the service response to contain only the desired details about the category. By default all details of a category are shown. (Optional) Ex. product, facet, attribute.
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Category Brand Index v4/catalog/category/brandindex/:categoryId

This API allows users to specify Category(s) and retrieve the complete list of Brands for that Category(s). This is called the Brand Index. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:categoryId	int	Unique ID for each category. Multiple Category ID's can be sent in one call by comma separating them. (Required) Ex. 3111
refcatid	string	Reference Category ID. This is an higher level category ID for the category you are trying to get brand index information for. For instance your higher level Category would be Womens (refcatid=118) and your nested category ID would be Jeans (3111). (Optional) Ex. 118
callback	int	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.(Optional) Ex. magicofmacysapi

GET Category Browse Product v3/catalog/category/:categoryId/browseproducts

The GetCategoryBrowse API call retrieves a list of products from a given category allowing you to browse the products. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:categoryId	int	Category ID (Required) Ex. 118
resultsperpage	string	Results per page (Number 1-100). Default is 12. (Optional) Ex. 20
currentpage	string	Current page number requested. Default: 1 (Optional) Ex. 3
show	string	You can use this parameter to show only products or only facets . We return both facets and products by default.(Optional) Ex. product, facet.
sortby	string	Sort By (Optional) Ex. customerrating
sortorder	string	Sort Order(Optional) Ex. asc
imagewidth	string	Image Width(Optional) Ex.100 (Pixels)
imagequality	string	Image Quality (Optional) Ex. 90
upcimagewidth	string	UPC Image Width (Optional) Ex.100 (Pixels)
swatchimagewidth	string	Swatch Image Width (Optional) Ex.100 (Pixels)
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Index v3/catalog/product/index

Get all products in our database using Product ID. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
category	string	Use this parameter to narrow the products returned by category ID. (Optional) Ex. 118
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Detail V3 (Using Product ID) v3/catalog/product/:productId

Get product details in our database using Product ID. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:productId	int	Product ID(s). Multiple products can be returned if you separate the Product ID's with commas. (Required) Ex. 77589,166725
show	string	You can specify which values are returned. By default we return each attribute except Reviews and Promotion. To return this data you will need to be specified using the 'show' query parameter. You can specify multiple values by comma separating them. Available values: summary, price, attribute, promotion, image, category, availability, rebate, upc, review (Optional) Ex. summary or summary,price,rebate
imagewidth	string	Image Width (Optional) Ex.100 (Pixels)
imagequality	string	Image Quality (Optional) Ex.90
upcimagewidth	string	UPC Image Width (Optional) Ex.100 (Pixels)
swatchimagewidth	string	Swatch Image Width (Optional) Ex.100 (Pixels)
numOfReviews	string	Number of Reviews (Optional) Ex. 3
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Detail V3 (Using UPC) v3/catalog/product

Get product details in our database using UPC. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
upc	int	UPC of the product. Multiple products can be returned if you separate the UPC's with commas. (Required) Ex. 50946872827,4003683257743
show	string	You can specify which values are returned. By default we return each attribute except Reviews and Promotions. To return this data you will need to use the 'show' query parameter. You can specify multiple values by comma separating them. Available values: summary, price, attribute, promotion, image, category, availability, rebate, upc, review (Optional) Ex. summary or summary,price,rebate
imagewidth	string	Image Width (Optional) Ex.100 (Pixels)
upcimagewidth	string	UPC Image Width (Optional) Ex.100 (Pixels)
swatchimagewidth	string	Swatch Image Width (Optional) Ex.100 (Pixels)
numOfReviews	string	Number of Reviews (Optional) Ex. 3
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Detail V4 (Using Product ID) v4/catalog/product/:productId

Get product details in our database using Product ID. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:productId	int	Product ID(s). Multiple products can be returned if you separate the Product ID's with commas. (Required) Ex. 77589,166725 You can also specify what objects are returned here. Please visit the static documentation to view details
retrieveallupcs	string	The parameter retrieveallupcs can be set to true or false. When set to true all upcs including inactive or unavailable upcs are returned. By default it is set to false. (Optional) Ex.false
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Detail V4 (Using UPC ID) v4/catalog/product/upc/:upcId

Get product details in our database using Product ID. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:upcId	int	Multiple UPCs can be returned if you separate the UPC ID's with commas. (Required) Ex. 50946872827. You can also specify what objects are returned here. Please visit the static documentation to view details
retrieveallupcs	string	The parameter retrieveallupcs can be set to true or false. When set to true all upcs including inactive or unavailable upcs are returned. By default it is set to false. (Optional) Ex.false
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Product Recommendations V4 v4/recommendations/product/:productId

The Product recommendations service allows you to specify a product and return related products that are recommended just as is done on Macys.com. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:productId	int	Product ID of the product you would like to return recommendations for (Required) Ex. 77589.
visitorid	string	Visitor ID is a unique ID that captures a person's session. (Required) Ex.123456789
maxprods	string	Max product returned. Default is 10. This number should be between 1 and 9.(Optional) Ex.5
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET BOPS Product Availability (Using Product ID) V4 v4/catalog/bops/product/:productId

The V4 BOPS (Buy Online Pick-up in Store) Product Availability service allows you specify a Product ID and return the products BOPS availability at a nearby store using zipcode, city-state, or locationnumber. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:productId	int	Product ID of the product you would like to return BOPS availability for. Multiple Product ID's can be specified here by comma separating. (Required) Ex. 77589. You can also specify what objects are returned here. Please visit the static documentation to view details
locationNumber	int	Location number of the area you are trying to locate a BOPS product. Required if you do not specify latitude/longitude, zipcode or city/state. (Optional) Ex.5459
latitude	int	BOPS look up by global coordinates. You must specify longitude parameter if you specify the latitude parameter. Required if you do not specify locationNumber, zipcode or city/state. (Required if also using longitude parameter) Ex. 37.355965
longitude	int	BOPS look up by global coordinates. You must specify latitude parameter if you specify the longitude parameter. First in priority if city and state and/or zipcode also supplied.(Required if also using latitude parameter) Ex. -122.01318
zipCode	int	Zip code of area you are trying to locate a BOPS product. Required if you do not specify locationNumber or city/state. (Optional) Ex.94105
city	string	Zip code of area you are trying to locate a BOPS product. You must specify state parameter if you specify the city parameter. Required if you do not specify locationNumber, latitude/longitude, or zipcode. (Optional) Ex.San Francisco
state	string	Zip code of area you are trying to locate a BOPS product. You must specify city parameter if you specify the state parameter. Required if you do not specify locationNumber, latitude/longitude, or zipcode. (Optional) Ex.CA
distance	string	Distance from location specified above using the locationNumber, zipcode, or city/state parameter. Default is 200 (miles). Can be a number between 1-200. (Optional) Ex.50
numberOfStores	string	Distance from location specified above using the locationNumber, zipcode, or city/state parameter. Default is 15. Can be a number between 1-15. (Optional) Ex.5
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET BOPS Product Availability (Using UPC ID) V4 v4/catalog/bops/upc/:upcId

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:upcId	int	Product ID of the product you would like to return BOPS availability for. Multiple Product ID's can be specified here by comma separating. (Required) Ex. 50946872827,96018254016 . You can also specify what objects are returned here. Please visit the static documentation to view details
locationNumber	int	Location number of the area you are trying to locate a BOPS product. Required if you do not specify latitude/longitude, zipcode or city/state. (Optional) Ex.5459
latitude	int	BOPS look up by global coordinates. You must specify longitude parameter if you specify the latitude parameter. Required if you do not specify locationNumber, zipcode or city/state. (Required if also using longitude parameter) Ex. 37.355965
longitude	int	BOPS look up by global coordinates. You must specify latitude parameter if you specify the longitude parameter. First in priority if city and state and/or zipcode also supplied.(Required if also using latitude parameter) Ex. -122.01318
zipCode	int	Zip code of area you are trying to locate a BOPS product. Required if you do not specify latitude/longitude, locationNumber or city/state. (Optional) Ex.94105
city	string	Zip code of area you are trying to locate a BOPS product. You must specify state parameter if you specify the city parameter. Required if you do not specify latitude/longitude, locationNumber or zipcode. (Optional) Ex.San Francisco
state	string	Zip code of area you are trying to locate a BOPS product. You must specify city parameter if you specify the state parameter. Required if you do not specify latitude/longitude, locationNumber or zipcode. (Optional) Ex.CA
distance	string	Distance from location specified above using the locationNumber, zipcode, or city/state parameter. Default is 200 (miles). Can be a number between 1-200. (Optional) Ex.50
numberOfStores	string	Distance from location specified above using the locationNumber, zipcode, or city/state parameter. Default is 15. Can be a number between 1-15. (Optional) Ex.5
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Search Phrase v4/catalog/search

Search for a product using string. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
searchphrase	int	Search for a product using string (Required) Ex. red dress
show	string	Shows products or facets only. If neither product or facet requested, shows BOTH products AND facets (Optional) Ex. product
sortorderby	string	Sorts order of response by PRICE_ASCENDING, PRICE_DESCENDING, CUSTOMER_RATING, NEWNESS, BEST_SELLERS (Optional)Ex. BEST_SELLERS
perpage	string	Default 12. not more than 24 per page (Optional) Ex. 4
page	string	What is current page number requested. Default 1 (Optional) Ex. 2
imagewidth	string	Image Width (Optional) Ex.100 (Pixels)
imagequality	string	Image Quality (Optional) Ex.90
upcimagewidth	string	UPC Image Width (Optional) Ex.100 (Pixels)
swatchimagewidth	string	Swatch Image Width (Optional) Ex.100 (Pixels)
include	string	This parameter allows you to return additional information about products such as promotions and product description. NOTE: Can only be used if the show=product also. Multiple values can be sent by separating them by Comma's. Currently promo and proddesc are the only two available. (Optional) Ex. promo,proddesc
avoidredirects	string	When a search input includes the name of a Macy's category we return the category ID in the response as a redirect instead of the products and facets that would normally be delivered. (Ex. Search phrase: chanel) You can avoid this by seeing this parameter to true. Default is false. (Optional) Ex.true
facetexpandall	string	When a user wants to see ALL facet values listed for the search. Default will show only first 10 values for each facet. Default is false. (Optional) Ex.true
invassort	string	Pass Inventory Assortment value to retreive Context specifc to return customized search results. Default is SITE (Optional)Ex. STORE
appl	string	Pass Application value to retreive Context specifc to return customized search results. Default is ASSOCIATE (Optional)Ex. SITE
device	string	Pass Device value to retreive Context specifc to return customized search results. Default is TABLET (Optional)Ex. PHONE
country	string	Pass Country value to retreive Context specifc to return customized search results. Default is US (Optional)Ex. US
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi
zip	string	Zip code of area you are trying to search for a product. Required if you do not specify locationNumber or city/state. (Optional) Ex.94105
city	string	You must specify state parameter if you specify the city parameter. (Optional) Ex.San Francisco
state	string	You must specify city parameter if you specify the state parameter. (Optional) Ex.CA
latitude	string	Search by global coordinates. You must specify longitude parameter if you specify the latitude parameter. (Required if also using longitude parameter) Ex. 37.355965
longitude	string	Search by global coordinates. You must specify latitude parameter if you specify the longitude parameter.(Required if also using latitude parameter) Ex. -122.01318

GET Reviews v3/catalog/reviews

GetCatalogReviews retrieves information about macys.com customer reviews. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
productId	string	Product id from the website - Web Id. (Required) Ex. 199462
numOfReviews	string	Must be number. Defaults to 10 if not sent in this parameter. (Optional) Ex. 3
pageNumber	string	You can specify which page you return. For instance if there are 20 reviews and you are returning 10 reviews per page then you could specify page 2 to get the second page of reviews. Default is 1 (Optional) Ex. 2
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Refresh Status v3/job/refreshjobstatus

The refreshstatus Service is a read only resource that returns the status and time of last data refresh. Please click here for the additional documentation.

Parameter	Value	Type	Description
accept		string	Output format as JSON or XML (Required) Ex. JSON
callback		string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

Shopping Bag Services

List Methods

Expand Methods

GET Retrieve Bag order/v1/bags

This service allows to retrieve bag. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
userId	int	This will be returned once you retrieve bag using the bagId. If bagId,userGuid, or bagGuid is not provided userId must be provided. (Optional) Ex. 7788802192
userGuid	string	This will be returned once you retrieve bag using the bagId. If bagId, userId, or bagGuid is not provided userGuid must be provided. (Optional) Ex. d0b93f0e-7b0d-4775-8fa7-d47a15951558
bagId	int	Bag ID is displayed on the website Shopping Bag page. If userId, userGuid, or bagGuid is not provided bagId must be provided.(Optional) Ex. 222115407
bagGuid	string	This will be returned once you retrieve bag using the bagId. If bagId, userGuid, or userId is not provided bagGuid must be provided. (Optional) Ex. cdfb23bc-8afe-4210-aaf2-69b55f1540da
promocode	string	A list of promocodes to be added. Multiple codes can passed by separating them by commas. Ex. MEMMOB or MEMMOB, SAVE
bagOptions	string	A list of promocodes to be added. Multiple attributes can passed by separating them by commas. Ex. INCLUDE_SAVED_BAG or INCLUDE_PRODUCTINFO
storeLocNumber	string	The location number of the store you would like to see product availability for. Ex. 73
cardType	string	Certain promotions or offers are returned depending on the Credit Card type that will be used. Click on the documentation link above for more details on the acceptable values Ex. Y
registryId	int	This is used if you are adding an item to your bag that belongs to a registry. Registry options will be provided if this ID is provided. Ex. 2055190
channelType	string	This is the channel of the application calling the service. Currently Mobile is the only valid channel. Ex. Mobile

POST Add to Bag order/v1/bags

This service allows to add items to shopping bag. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
Content-Type	string	Content type of the payload body as JSON or XML
userId	int	This will be returned once you retrieve bag using the bagId. If userId or userGuid is not provided a guest bag and guest user is created. (Optional) Ex. 7788802192
userGuid	string	If userId or userGuid is not provided a guest bag and guest user is created. (Optional) Ex. d0b93f0e-7b0d-4775-8fa7-d47a15951558
promocode	string	A list of promocodes to be added. Multiple codes can passed by separating them by commas. Ex. MEMMOB or MEMMOB, SAVE
bagOptions	string	A list of promocodes to be added. Multiple attributes can passed by separating them by commas. Ex. INCLUDE_SAVED_BAG or INCLUDE_PRODUCTINFO
storeLocNumber	string	The location number of the store you would like to see product availability for. Ex. 73
cardType	string	Certain promotions or offers are returned depending on the Credit Card type that will be used. Click on the documentation link above for more details on the acceptable values Ex. Y
registryId	int	This is used if you are adding an item to your bag that belongs to a registry. Registry options will be provided if this ID is provided. Ex. 2055190
scanStoreLocationNumber	int	The location number of the store your scaning from. (Typically used with an application that can scan bar codes) This parameter is used to see if the user qualifies for any store promotions or discounts. Ex. 73
channelType	string	This is the channel of the application calling the service. Currently Mobile is the only valid channel. Ex. Mobile

Request Body

PATCH Update Bag order/v1/bags/:bagGuid/items

This service enables users update quantity of items that is already added to a shopping bag. It enables users edit multiple items with each request. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
Content-Type	string	Content type of the payload body as JSON or XML
:bagGuid	string	Bag Guid. This Bag Guid can be found when creating a guest bag or adding and item to your bag. (Required) Ex. cdfb23bc-8afe-4210-aaf2-69b55f1540da
promocode	string	A list of promocodes to be added. Multiple codes can passed by separating them by commas. Ex. MEMMOB or MEMMOB, SAVE
bagOptions	string	A list of promocodes to be added. Multiple attributes can passed by separating them by commas. Ex. INCLUDE_SAVED_BAG or INCLUDE_PRODUCTINFO
storeLocNumber	string	The location number of the store you would like to see product availability for. Ex. 73
cardType	string	Certain promotions or offers are returned depending on the Credit Card type that will be used. Click on the documentation link above for more details on the acceptable values Ex. Y
registryId	int	This is used if you are adding an item to your bag that belongs to a registry. Registry options will be provided if this ID is provided. Ex. 2055190
scanStoreLocationNumber	int	The location number of the store your scaning from. (Typically used with an application that can scan bar codes) This parameter is used to see if the user qualifies for any store promotions or discounts. Ex. 73
channelType	string	This is the channel of the application calling the service. Currently Mobile is the only valid channel. Ex. Mobile

Request Body

DELETE Delete Item from Bag order/v1/bags/:bagGuid/items/:sequenceNumber

This service allows you to delete an item from the shopping bag. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
Content-Type	string	Content type of the payload body as JSON or XML
:bagGuid	int	Bag Guid. This Bag Guid can be found when creating a guest bag or adding and item to your bag. (Required) Ex. cdfb23bc-8afe-4210-aaf2-69b55f1540da
:sequenceNumber	int	This is the Item Sequence Number. This is required to delete the correct item (Required) Ex. 21
promocode	string	A list of promocodes to be added. Multiple codes can passed by separating them by commas. Ex. MEMMOB or MEMMOB, SAVE
bagOptions	string	A list of promocodes to be added. Multiple attributes can passed by separating them by commas. Ex. INCLUDE_SAVED_BAG or INCLUDE_PRODUCTINFO
storeLocNumber	string	The location number of the store you would like to see product availability for. Ex. 73
cardType	string	Certain promotions or offers are returned depending on the Credit Card type that will be used. Click on the documentation link above for more details on the acceptable values Ex. Y
registryId	int	This is used if you are adding an item to your bag that belongs to a registry. Registry options will be provided if this ID is provided. Ex. 2055190
gwpIndicator	boolean	Indicator that defines whether or not the item is a GWP (Gift with Purchase) or not. Ex. True
channelType	string	This is the channel of the application calling the service. Currently Mobile is the only valid channel. Ex. Mobile

Request Body

Promotions and Coupon Services

List Methods

Expand Methods

GET Promotions v2/promotions

This service allows to retrieve promotions. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
promoid	string	Promotional ID (Optional) Ex. 402902
global	string	Specifies if the promotion global or not (Optional) Ex. Y
sourcecode	string	sourcecode (Optional) Ex. D
type	string	Promotion Type (Optional) Ex. Bundled GWP
promo_code	string	Promotion Code (Optional) Ex. 402903
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Promotions and Coupons v3/promotions

This service allows to retrieve promotions, coupons, or both using one call. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
show	string	Specifies if you would like to return promotions, coupons, or promotions AND coupons (Required) Ex. promotions,coupons
promoid	string	Promotional ID (Optional) Ex. 402902
global	string	Specifies if the promotion global or not (Optional) Ex. Y
promotionsourcecode	string	Promotion Sourcecode (Optional) Ex. D
promotype	string	Promotion Type (Optional) Ex. Bundled GWP
promocode	string	Promotion Code (Optional) Ex. VETDAY
channel	string	Channel for Promotion or Coupon (Optional) Ex. MOBILE
coupontype	string	Coupon Type (Optional) Ex. Other
couponnumber	string	Coupon filter Number(Optional) Ex. 00030492100318133415
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Promotions Sorted v3/promotions/sorted

The Promotions Sorted API call allows the users to get Deals and Promotion data set grouped and sorted by FOB to match data rendered on website. Please click here for the additional documentation.

Parameter	Value	Type	Description
accept		string	Output format as JSON or XML (Required) Ex. JSON
channel		string	Channel for the Promotion (Optional) Ex. SITE

POST Promotions Share v3/promotions/share

The Promotions Share API allows users to use a POST call to send automated emails to recipient(s) about MACY's Promotions or Coupons. Please click here for the additional documentation.

Parameter	Value	Type	Description
accept		string	Output format as JSON or XML (Required) Ex. JSON
Content-Type		string	Content type of the payload body as JSON or XML

Request Body

GET Coupons v2/promotions/coupons

This service allows to retrieve coupons. Please click here for the additional documentation.

Parameter	Value	Type	Description
accept		string	Output format as JSON or XML (Required) Ex. JSON
callback		string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

Registry Services

List Methods

Expand Methods

GET Registry by Name (GVR) v2/registry/by-name

This service returns the Guest View Registry (GVR) Registry ID based on Name. You can narrow your results by specifying month and year of event. Once you have the correct Registry ID you can use the Get Registry by Registry ID (GVR) (below) to return the products of that specific registry. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
firstName	string	Enter First name of Bride, Groom, or Guest of Honor (Required) Ex. David
lastName	string	Enter Last name of Bride, Groom, or Guest of Honor (Required) Ex. Smith
eventYear	string	Year of Registry Event. (Required only if you choose to also query by eventMonth parameter.) Ex. 2013
eventMonth	string	Month of event: 1-12. (Optional: However, you must use the eventYear parameter to specify this parameter of registry specified.) Ex. For May use 5
registryType	string	Default to WEDDING. Currently WEDDING is the only registry supported through this service (Optional) Ex. WEDDING
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

GET Registry by Registry ID (GVR) v2/registry/by-id/:registryID

This service returns products shown in the Guest View Registry (GVR) when a request is made by Registry ID. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:registryID	string	The unique identifier of this registry assigned when the registry was created. (Required) Ex. 2055190
type	string	This specifies this is a Guest View Registry (GVR) request (Required) Ex. GVR Note: a BVR (Bridal View Registry) is also available. This is a protected Services call
callback	string	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned. (Optional) Ex. magicofmacysapi

Store Services

List Methods

Expand Methods

GET Events store/v1/events

GetStoreEvents Provides a list of events in store for a given Store and date range. The search can be made by the storeId, locationNumber, or storeNumber. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
storeId	int	Store ID. You can return events for multiple stores by separating them by a comma. (Required if NOT searching by storeNumber) Ex. 212, 70
storeNumber	int	MST Store Number. You can return events for multiple stores by separating them by a comma. (Required if NOT searching by storeId) Ex. 428,49
locationNumber	int	Location Number for the Store. You can return events for multiple stores by separating them by a comma. (Required if NOT searching by storeId) Ex. 73,63
startDate	string	Start Search Date (Optional) Ex. 2014-01-01
finishDate	string	End Search Date (Optional) Ex. 2014-12-31
_fields	string	Filter parameter that allows you to return the exact fields you would like in the response. Multiple fields and subfields can be returnd by separating them by a comma and including subfields in parentheses. (Optional) Ex. name,locationNumber,attributes(attribute(name))

GET Location (Using Location Number) /store/v2/stores/:locationNumber

This service allows users to find store information based on Location Number. You can also request store availability information for products and upc's. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
:locationNumber	int	Product ID of the product you would like to return recommendations for (Required) Ex. 73,63.
feature	string	Response will be filtered by support of specific features in store. You can return by multiple features by comma separating. Supported values: BOPS, BRIDAL, HAS_EVENTS, MATTRESS, FURNITURE_GALLERY,VISITOR_CENTER, PERSONAL_SHOPPER, RESTAURANT (Optional) Ex. BOPS,BRIDAL
_fields	string	Filter Parameter that allows you to return just the fields you would like in the response (Optional) Ex. features,address,inventories,mapUrl,phoneNumber
upcNumber	int	Provides instore availability of a specific UPC at the store(s) you query. (Optional) Ex. 50946872827
productId	int	Provides instore availability of a specific product at the store(s) you query (Optional) Ex. 77589

GET Location store/v2/stores

This service allows users to find store information based on store number. You can also return store information base on location specified in a variety of ways. In addition you can request store availability information for products and upc's. If no location query parameters are provided you will return all store information. Please click here for the additional documentation.

Parameter	Type	Description
accept	string	Output format as JSON or XML (Required) Ex. JSON
storeNumber	int	This is the MST Store Number ZL_STORE_NBR. You can return multiple store information by comma separating. (Optional) Ex. 428,49
searchAddress	string	Input a string for this query parameter. This can be a city state combo, a full address, a general area, or even a zip code (Optional) Ex. 680 Folsom St San Francisco CA
latitude	int	Stores look up by global coordinates. (Optional) Ex. 37.355965
longitude	int	Stores look up by global coordinates. (Optional) Ex. -122.01318
radius	string	Radius (in miles) in which store should be located. Specified as Mnn e.g. M50, if not specified is set to M200 by default. Maximum radius is M200 (Optional)) Ex. M100
feature	string	Response will be filtered by support of specific features in store. You can return by multiple features by comma separating. Supported values: BOPS, BRIDAL, HAS_EVENTS, MATTRESS, FURNITURE_GALLERY,VISITOR_CENTER, PERSONAL_SHOPPER, RESTAURANT (Optional) Ex. BOPS,BRIDAL
_limit	int	Filter the number of stores being returned. By default we return all the stores in a 200 mile radius unless the radius is defined to be less. (Optional) Ex. 5
_fields	string	Filter Parameter that allows you to return just the fields you would like in the response (Optional) Ex. features,address,inventories,mapUrl,phoneNumber
upcNumber	int	Provides instore availability of a specific UPC at the store(s) you query. (Optional) Ex. 50946872827
productId	int	Provides instore availability of a specific product at the store(s) you query (Optional) Ex. 77589

Interactive API Console

Select an API Ad Media Services Catalog Services Bag Services Promotion & Coupon Services Registry Services Store Services

Ad Media Services List Methods Expand Methods

Catalog Services List Methods Expand Methods

Shopping Bag Services List Methods Expand Methods

Request Body

Request Body

Request Body

Promotions and Coupon Services List Methods Expand Methods

Request Body

Registry Services List Methods Expand Methods

Store Services List Methods Expand Methods

Ad Media Services

List Methods

Expand Methods

Catalog Services

List Methods

Expand Methods

Shopping Bag Services

List Methods

Expand Methods

Promotions and Coupon Services

List Methods

Expand Methods

Registry Services

List Methods

Expand Methods

Store Services

List Methods

Expand Methods