Edit

Catalogs Resource

  • Article

The Catalogs resource lets you manage catalogs in your Microsoft Merchant Center store (MMC). For information about using the Catalogs resources, see Managing your Catalogs. For examples that show how to add, delete, and get catalogs, see Code Examples.

Base URI

The following is the base URI that you append the templates to.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

Templates

To create the endpoints that you use to manage your catalogs, append the appropriate template to the base URI.

Template HTTP Verb Description Resource
{mmcMerchantId}/catalogs POST Use to add a catalog to the store. To add a catalog, its name must be unique. You may add a maximum of 100 catalogs to a store.

Set {mmcMerchantId} to the MMC store ID.		 Request: Catalog
Response: Catalog
{mmcMerchantId}/catalogs/{catalogId} PUT Use to update a catalog in the store. The only fields you may update are the name and isPublishingEnabled fields, and you must specify both.

Set {mmcMerchantId} to the MMC store ID.		 Request: Catalog
Response: Catalog
{mmcMerchantId}/catalogs/{catalogId} DELETE Use to delete a catalog from the store.

Set {mmcMerchantId} to the MMC store ID.

Set {catalogId} to the catalog's ID.		 Request: N/A
Response: N/A
{mmcMerchantId}/catalogs/{catalogId} GET Use to get a catalog from the store.

Set {mmcMerchantId} to the MMC store ID.

Set {catalogId} to the catalog's ID.		 Request: N/A
Response: Catalog
{mmcMerchantId}/catalogs GET Use to get a list of catalogs from the store.

Set {mmcMerchantId} to the MMC store ID.		 Request: N/A
Response: Catalogs

Query parameters

The endpoints may include the following query parameters.

Parameter Description
alt Optional. Use to specify the type of content that's used in the request and response. The possible values are json and xml. The default is json.

Headers

The following are the request and response headers.

Header Description
AuthenticationToken Request header.

Set this header to an OAuth authentication token. For information about getting a token, see Authenticating your credentials.
Content-Location Response header.

A URL that identifies the store that the catalog was inserted into. This header is included in the response of an Insert request.
CustomerAccountId Request header.

The account ID of any of the accounts that you manage on behalf of the customer specified in the CustomerId header. It doesn't matter which account you specify. Specify this header only if you manage an account on behalf of the customer.
CustomerId Request header.

The customer ID of the customer whose store you manage. Specify this header only if you manage the store on behalf of the customer. If you set this header, you must also set the CustomerAccountId header.
DeveloperToken Request header.

The client application's developer access token. Each request must include this header. For information about getting a token, see Do you have your Microsoft Advertising credentials and developer token?
Location Response header.

A URL that identifies the store that the catalog was inserted into. This header is included in the response of an Insert request.
WebRequestActivityId Response header.

The ID of the log entry that contains details about the request. You should always capture this ID if an error occurs. If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.

Request and response objects

The following are the request and response objects used by the API.

Each object defines the JSON key name and XML element name that you use depending on the content type that you specify for the request.

Object Description
Catalog Defines a catalog.
Catalogs Defines the list of catalogs.

Catalog

Defines a catalog.

Name Value Type XML element name
id An ID that uniquely identifies the catalog in the store.

This field is read-only; do not set this field.		 Unsigned Long <id>
isDefault A Boolean value that determines whether the catalog is the store's default catalog. Is true if the catalog is the store's default catalog; otherwise, false.

When you create a store, you get a default catalog that products are written to if you do not specify another catalog.

This field is read-only; do not set this field.		 Boolean <is_default>
isPublishingEnabled A Boolean value that determines whether Microsoft may publish products from the catalog. Set to true if Microsoft may publish products from the catalog; otherwise, set it to false.

You may update this field.

You can also use this field to test your application before deploying it to production. By setting this field to false, you may make Products Resource calls without changing or publishing your production data.		 Boolean <is_publishing_enabled>
market The market where products in the catalog are published to.

NOTE: Not everyone has this feature yet. If you don't, don't worry—its coming soon!.

The following are the possible markets that you may specify.
  • Albania, Albanian (sq-AL)
  • Andorra, French (fr-AD)
  • Argentina, Spanish (es-AR)
  • Aruba, English (en-AW)
  • Australia, English (en-AU)
  • Austria, German (de-AT)
  • Bahamas, English (en-BS)
  • Bangladesh, English (en-BD)
  • Belgium, Dutch (nl-BE)
  • Belgium, French (fr-BE)
  • Bolivia, Spanish (es-BO)
  • Bosnia and Herzegovina, Bosnian (bs-BA)
  • Brazil, Portuguese (pt-BR)
  • Brunei, English (en-BN)
  • Bulgaria, Bulgarian (bg-BG)
  • Canada, English (en-CA)
  • Canada, French (fr-CA)
  • Cayman Islands, English (en-KY)
  • Chile, Spanish (es-CL)
  • Colombia, Spanish (es-CO)
  • Costa Rica, Spanish (es-CR)
  • Croatia, Croatian (hr-HR)
  • Cyprus, English (en-CY)
  • Cyprus, Greek (el-CY)
  • Czech Republic, Czech (cs-CZ)
  • Denmark, Danish (da-DK)
  • Dominica, English (en-DM)
  • Dominican Republic, Spanish (es-DO)
  • Ecuador, Spanish (es-EC)
  • El Salvador, Spanish (es-SV)
  • Estonia, Estonian (et-EE)
  • Fiji, English(en-FJ)
  • Finland, Finnish (fi-FI)
  • France, English (en-FR)
  • France, French (fr-FR)
  • French Guiana, French (fr-GF)
  • French Polynesia, French (fr-PF)
  • Germany, English (en-DE)
  • Germany, German (de-DE)
  • Greece, English (en-GR)
  • Greece, Greek (el-GR)
  • Guam, English (en-GU)
  • Guatemala, Spanish (es-GT)
  • Guyana, English (en-GY)
  • Haiti, French (fr-HT)
  • Honduras, Spanish (es-HN)
  • Hong Kong SAR, Traditional Chinese (zh-HK)
  • Hungary, English (en-HU)
  • Hungary, Hungarian (hu-HU)
  • Iceland, Icelandic (is-IS)
  • India, English (en-IN)
  • Indonesia, English (en-ID)
  • Ireland, English (en-IE)
  • Italy, English (en-IT)
  • Italy, Italian (it-IT)
  • Japan, Japanese (ja-JP)
  • Latvia, Latvian (lv-LV)
  • Liechtenstein, German (de-LI)
  • Lithuania, Lithuanian (lt-LT)
  • Luxembourg, French (fr-LU)
  • Luxembourg, German (de-LU)
  • Malaysia, English (en-MY)
  • Maldives, English (en-MV)
  • Malta, Maltese (mt-MT)
  • Martinique, French (fr-MQ)
  • Mexico, Spanish (es-MX)
  • Monaco, French (fr-MC)
  • Mongolia, English (en-MN)
  • Montenegro, English (en-ME)
  • Montenegro, Serbian (sr-ME)
  • Montserrat, English (en-MS)
  • Nepal, English (en-NP)
  • Netherlands, Dutch (nl-NL)
  • Netherlands, English (el-NL)
  • New Caledonia, French (fr-NC)
  • New Zealand, English (en-NZ)
  • North Macedonia, Macedonian (mk-MK)
  • Norway, Norwegian (nb-NO)
  • Panama, Spanish (es-PA)
  • Papua New Guinea, English (en-PG)
  • Paraguay, Spanish (es-PY)
  • Peru, Spanish (es-PE)
  • Phillippines, English (en-PH)
  • Poland, Polish (pl-PL)
  • Portugal, Portuguese (pt-PT)
  • Puerto Rico, Spanish (es-PR)
  • Romania, Romanian (ro-RO)
  • San Marino, English (en-SM)
  • San Marino, Italian (it-SM)
  • Serbia, English (en-RS)
  • Serbia, Serbian (sr-RS)
  • Singapore, English (en-SG)
  • Slovakia, English (en-SK)
  • Slovakia, Slovak (sk-SK)
  • Slovenia, Slovenian (sl-SI)
  • South Africa, English (en-ZA)
  • Spain, English (en-ES)
  • Spain, Spanish (es-ES)
  • Sri Lanka, English (en-LK)
  • Sweden, English (en-SE)
  • Sweden, Swedish (sv-SE)
  • Switzerland, German (de-CH)
  • Switzerland, French (fr-CH)
  • Taiwan, Traditional Chinese (zh-TW)
  • Thailand, English (en-TH)
  • Trinidad and Tobago, English (en-TT)
  • Türkiye, Turkish (tr-TR)
  • United Kingdom, English (en-GB)
  • United States, English (en-US)
  • United States, Spanish (es-US)
  • Uruguay, Spanish (es-UY)
  • Vatican City, Italian (it-VA)
  • Venezuela, Spanish (es-VE)
  • Vietnam, English (en-VN)
All products that you add to the catalog must specify the same market (see contentLanguage and targetCountry).

You may not update this field after adding the catalog to the store.

In the above list, de-DE is the market value that you specify; do not include (German-Germany) in your market string.		 String <market>
name The name of the catalog. The name may contain a maximum of 70 characters.

You may update this field.		 String <name>

Catalogs

Defines a list of catalogs.

Name Value Type XML element name
catalogs A list of catalogs in the store. Catalog[] <catalogs>

HTTP status codes

The requests may return the following HTTP status codes.

Status code Description
200 Success.
201 Successfully added the catalog.
204 Successfully deleted the catalog.
400 Bad request. Either a query parameter value is not valid or something in the request body is not valid.
401 Unauthorized. The user's credentials are not valid.
404 Not found.
500 Server error.