Catalogs Resource
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.
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. |