Catalogs Resource

 

The Catalogs resource lets you manage catalogs in your Bing Merchant Center store (BMC). 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.

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

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

You may use the above Base URI or the Tenant URL shown under Store settings in the Bing Ads web application.

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

TemplateHTTP VerbDescriptionResource
{bmcMerchantId}/catalogsPOSTUse 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 {bmcMerchantId} to the BMC store ID.
Request: Catalog
Response: Catalog
{bmcMerchantId}/catalogsPUTUse to update a catalog in the store. You may update only the name and isPublishingEnabled fields, and you must specify both.

Set {bmcMerchantId} to the BMC store ID.
Request: Catalog
Response: Catalog
{bmcMerchantId}/catalogs/{catalogId}DELETEUse to delete a catalog from the store.

Set {bmcMerchantId} to the BMC store ID.

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

Set {bmcMerchantId} to the BMC store ID.

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

Set {bmcMerchantId} to the BMC store ID.
Request: N/A
Response: Catalogs

The endpoints may include the following query parameters.

ParameterDescription
altOptional. 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.

The following are the request and response headers.

HeaderDescription
AuthenticationTokenRequest header.

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

This header and the UserName header are mutually exclusive.
Content-LocationResponse header.

A URL that identifies the store that the product was inserted into. This header is included in the response of an Insert request.
CustomerAccountIdRequest 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.
CustomerIdRequest 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.
DeveloperTokenRequest 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 Bing Ads credentials and developer token?.
LocationResponse header.

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

A Bing Ads user's sign-in password. Specify this header only if you use the UserName header; do not specify this header with the AuthenticationToken header.
UserNameRequest header.

A Bing Ads user's sign-in user name. You may not set this element to a Microsoft account or email address. This header and the AuthenticationToken header are mutually exclusive.
WebRequestActivityIdResponse header.

The ID of the log entry that contains the details of 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.

For user authentication, specify either the AuthenticationToken header or the UserName and Password headers. New customers are required to use a Microsoft account when they sign up for Bing Ads, which uses OAuth to authenticate the user. Existing users with legacy Bing Ads credentials may continue to specify the UserName and Password headers. In future versions of the API, Bing Ads will transition exclusively to using Microsoft accounts.

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.

ObjectDescription
CatalogDefines a catalog.
CatalogsDefines the list of catalogs.

Catalog

Defines a catalog.

NameValueTypeXML element name
idAn ID that uniquely identifies the catalog in the store.

This field is read-only; do not set this field.
Unsigned Long<id>
isDefaultA 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>
isPublishingEnabledA Boolean value that determines whether Bing may publish products from the catalog. Set to true if Bing may publish products from the catalog; otherwise, set it to false.

You may update this field.

You 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>
marketThe market where products in the catalog are published to. The following are the possible markets that you may specify.

- de-DE (German-Germany)
- en-AU (English-Australia)
- en-GB (English-Great Britain)
- en-US (English-United States)
- fr-FR (French-France)

All products that you add to the catalog must specify the same market (see contentLanguage and targetCountry).

You may not update this field after the catalog is added 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>
nameThe name of the store. The name may contain a maximum of 70 characters.

You may update this field.
String<name>

Catalogs

Defines a list of catalogs.

NameValueTypeXML element name
catalogsA list of catalogs in the store.Catalog[]<catalogs>

The requests may return the following HTTP status codes.

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