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.
| Template | HTTP Verb | Description | Resource |
|---|---|---|---|
{bmcMerchantId}/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 {bmcMerchantId} to the BMC store ID. | Request: Catalog Response: Catalog |
{bmcMerchantId}/catalogs | PUT | Use 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} | DELETE | Use 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} | GET | Use 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}/catalogs | GET | Use 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.
| 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. |
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. This header and the UserName header are mutually exclusive. |
| Content-Location | Response header. A URL that identifies the store that the product 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 Bing Ads credentials and developer token?. |
| Location | Response header. A URL that identifies the store that the product was inserted into. This header is included in the response of an Insert request. |
| Password | Request 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. |
| UserName | Request 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. |
| WebRequestActivityId | Response 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.
| 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 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> |
| market | The 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> |
| name | The 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.
| Name | Value | Type | XML element name |
|---|---|---|---|
| catalogs | A list of catalogs in the store. | Catalog[] | <catalogs> |
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. |