Managing your Products

Content API is a RESTful API that uses the Products resource to manage product offerings in your Microsoft Merchant Center (MMC) store.

The following is the base URI that you use to call the Content API.

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

Each HTTP request must include the user's OAuth access token and your developer token. To specify the user's access token, set the AuthenticationToken header. To specify your developer token, set the DeveloperToken header.

If you manage catalogs on behalf of other customers, you must set:

• The CustomerId header to the customer ID of the customer whose store you're managing.
• The CustomerAccountId header to the account ID of any of the customer's accounts that you manage (it doesn't matter which managed account).

By default, the Content API uses JSON objects to represent the product offer. To use XML, set the alt query parameter to XML.

For details about using the Products resource, see the following sections.

• Getting a product offer from the store
• Getting a list of product offers from the store
• Deleting an offer from the store
• Adding and updating a product offer
• Using batch processing

Getting a product offer from the store

To get a specific product offer from the store, append the following template to the base URI.

{mmcMerchantId}/products/{productUniqueId}

Set {mmcMerchantId} to your MMC store ID and set {productUniqueId} to the fully qualified product ID (for example, Online:en:US:Sku123), not the product's offerId. Because the product ID is case sensitive, use the ID that the API returned to you when you added the product.

Send an HTTP GET request to the resulting URL. If the product was found, the response contains a Product object that contains the offer.

If you inserted a product with the same ID in multiple catalogs, the service returns only one of them— which product and from which catalog is undetermined. Because of this, you should not insert a product with the same product ID into multiple catalogs.

For a code example that shows how to get a product offer, see Managing Products Code Example.

Getting a list of product offers from the store

To get a list of the product offers that are in the store, append the following template to the base URI.

{mmcMerchantId}/products

Set {mmcMerchantId} to your MMC store ID.

To page through the list of offers, use the max-results and start-token query parameters. In your first call, set max-results to the maximum number of offers that you want the service to return. The maximum number of offers that the service can return is 250. The default is 25. Send an HTTP GET request to the resulting URL. The following shows an example of the request.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

If the store contains offers, the response contains a Product object that contains up to the requested number of offers.

If there are more offers available, the response includes the nextPageToken field (see Products). The nextPageToken field contains the token value that you use to set the start-token parameter to in your next List request. The following shows an example that uses the token.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

For a code example that shows how to get a list of product offers, see Managing Products Code Example.

Deleting an offer from the store

To delete a specific product offer from the store, append the following template to the base URI.

{mmcMerchantId}/products/{productUniqueId}

Set {mmcMerchantId} to your MMC store ID and set {productUniqueId} to the fully qualified product ID (for example, Online:en:US:Sku123), not the product's offerId. Because the product ID is case sensitive, use the ID that the API returned to you when you added the product.

Send an HTTP DELETE request to the resulting URL. If the product was found, it is deleted.

If you inserted a product with the same product ID in multiple catalogs, the service deletes all of them. You should not insert a product with the same product ID into multiple catalogs.

For a code example that shows how to delete a product offer, see Managing Products Code Example.

Adding and updating a product offer

Adding or updating an offer is an insert operation. Because an update is an insert operation, you must include all fields of the offer in the request; you cannot not update a single field.

To insert a product offer, append the following template to the base URI.

{mmcMerchantId}/products

Set {mmcMerchantId} to your MMC store ID.

Sending an HTTP POST request to the resulting URL writes the offer to the default store catalog. To write the offer to a specific catalog, include the bmc-catalog-id query parameter.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

If the product was inserted, the response contains a Product object. The Product object includes the product ID, which you use to get and delete the offer.

An offer must include the following fields:

• availability
• channel
• condition
• contentLanguage
• imageLink
• link
• offerId
• price
• targetCountry
• title

The API uses the channel, contentLanguage, targetCountry, and offerId to generate the product ID. Because these fields are used to generate the ID, you may not update them. The product ID is case sensitive; the ID uses the same casing that you used to specify channel, contentLanguage, targetCountry, and offerId.

Caution

Be sure to use the same casing for channel, contentLanguage, targetCountry, and offerId because you can effectively add the same product multiple times if the casing is different.

The following fields are also required if the manufacturer assigned values.

• brand
• gtin
• mpn

You must specify the values if known. If you do not specify any of them, you must set the identifierExists field to false. The default is true.

If the product is known to have these identifiers and you do not specify them, MMC accepts the product for now but the Product object in the response includes the warnings field. You should always check if the warnings field exists and fix all identified issues.

In addition to the required fields, you should also specify the date and time that you want the offer to expire (see expirationDate). By default, the offer expires 30 days from the date and time it is written to the store or catalog. You should track products that are nearing expiration and before they expire either update their expiration date or simply update the product (you do not have to update any of the product's fields), which automatically extends the expiration date another 30 days. If you explicitly set the expiration date, you must set a new expiration date yourself; updating the product won't automatically extend the expiration date another 30 days in this case.

All other fields are considered optional; however, you should specify as many as are necessary to accurately describe the product.

Note

The Product object must include only fields that are set to values. Do not include null fields in the Product object. For example, do not include "adult":null.

Microsoft does not use all the Product fields. For a list of fields that the API accepts but does not use, see What Google attributes can I use? All the other fields used by Microsoft are used to filter the products when serving product ads.

If you specify a field that is unknown to the Content API, the service ignores the field.

When you insert an offer, the service performs basic validations on the offer and returns errors and warnings as appropriate. If an error occurs, the response contains an ErrorResponse object. If warnings occur, the response contains a Product object and the warnings field lists the warnings.

If the offer passes the basic validations, it undergoes offline validations and reviews, such as editorial reviews, that can take up to 36 hours. The offer won't serve until all validations and reviews are complete. To determine the status of an offer, use the Status resource.

Note that the API does not provide concurrency controls such as ETags. If two apps are trying to add or update the same product, the last one wins.

An offer that is displayed in a product ad includes the price, title, store name (or sellerName if specified), link to the webpage that contains more information about the product, and an image of the product.

For apparel products that are available in multiple colors, patterns or materials, create a product for each variant and use the itemGroupId field to group all product variants.

For a code example that shows how to insert a product offer, see Managing Products Code Example.

Using batch processing

If you're processing multiple product offers, you should consider using the API's batch processing feature. This feature lets you process multiple inserts, gets, and deletes in a single request. Processing multiple offers in the same request is more efficient than sending a separate request for each offer. The cost incurred with processing a single request is spread over the thousands of offers in the batch request instead of incurring that cost for each individual request.

Do not insert, get, or delete the same product in the same request.

To send a batch request, append the following template to the base URI.

{mmcMerchantId}/products/batch

Set {mmcMerchantId} to your MMC store ID.

Sending an HTTP POST request to the resulting URL applies the insert operations to the default store catalog. To apply the offers to a specific catalog, include the bmc-catalog-id query parameter.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

The body of the POST is a Batch object that contains an array of Item objects. For all operations, set the batchId, merchantId and method fields. The batchId is a user-defined ID that you use to identify the batch item in the response; the merchantId is your store ID; and the method is the operation to be performed (for example, insert, delete or get).

If method is insert, set the product field to a Product object that contains the offer to add or update. Otherwise, if method is a get or delete, set productId to the fully qualified ID of the offer that you want to get or delete.

The size of the body of a batch request may not exceed 4 MB. If the body exceeds 4 MB, the response returns HTTP status code 413. Depending on the size of each offer (the number of fields that you specify), you can send between 2,000 and 6,000 offers. If you compress the body, you can send the maximum number of offers, which is 12,000 (depending on their size).

To compress the body, use GZip compression only and set the request's Content-Encoding header to gzip.

The service processes each item in the batch. The response contains a Batch object that contains each Item that was in the request. Note that there is no guarantee that the order of the items in the response is in the same order as the items in the request.

For insert operations, the item includes only the batchId and product fields. The product field contains the same offer that you sent in the request but also includes the fully qualified product ID. If an error or warning occurs, the item includes the batchId, method, and error fields. The error field contains the reasons why the insert failed or warnings about issues with the offer that you need to fix.

For get operations, the item includes the batchId and product fields. The product field contains the offer that you requested. If the product is not found, the object won't include the product field.

For delete operations, the item includes only the batchId field; there is no indication of whether the offer exists and was deleted.

For a code example that shows how to use batch processing, see Creating a Batch Request.