Status Resource

The Status resource lets you get the status of product offers that you uploaded to the specified catalog. After you upload offers to the catalog, they go through a validation and editorial review process. This process can take up to a 36 hours. The offer is included in the report only after it completes the review process.

For an overview of how the process works, see How Do I Get the Status of Product Offers?

For a code example that shows how to get the catalog's status and download the report, see Downloading the Catalog Status Report.

Base URI

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.

Templates

To create the endpoints that you use to get the status of product offerings in a catalog, append the appropriate template to the base URI.

Template HTTP Verb Description Resource
{bmcMerchantId}/catalogs/{catalogId}/status GET Use to get the number of uploaded offers that passed or failed validation and editorial review.

Set {bmcMerchantId} to the BMC store ID.

Set {catalogId} to the catalog's ID.
Request: N/A
Response: Status

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

Important

The Bing Ads APIs, including Content API, will stop supporting managed user credentials (username and password) beginning August 1, 2018. At your earliest convenience, please migrate your account to use Microsoft accounts. For information, see We're changing the way you sign in. You will also need to change your code to use OAuth for authentication. For details about using OAuth, see Authentication with OAuth.

The following are the request and response headers.

Header Description
Accept Request header.<p>Include this header when you download the report. You must set this header to application/x-zip-compressed.
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.

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
Status Defines the status of the product offerings that were uploaded to the catalog.

Status

Defines the status of the product offerings that were uploaded to the catalog. XML object name: <catalogStatus>

Name Value Type XML element name
catalogId The ID of the catalog being reported. ulong <catalog_id>
publishedCount The number of offerings that passed validation and editorial review. ulong <published_count>
rejectedCount The number of offerings that failed validation and editorial review. This count indicates the number of rows in the body of the report (see Report Format). ulong <rejected_count>
rejectionReportUrl The URL that you use to download the report. The object includes this field only when rejectedCount is greater than zero.

The report is compressed and must be unzipped before you can read it.
string <catalog_id>

HTTP status codes

The requests may return the following HTTP status codes.

Status code Description
200 Success.
400 Bad request. Either a query parameter value is not valid or the report URL (see rejectionReportUrl) is no longer valid.
401 Unauthorized. The user's credentials are not valid.
404 Not found. Either status is not available for the specified catalog or the catalog or store ID is not valid.
500 Server error.

Report Format

The report file that you download is contained in a Zip compressed folder (*.zip). You must unzip the folder and its contents before you can read the report. The report is a comma-delimited file named MerchantCatalogReport.csv.

The report is broken out into a header section and report body section. The first row contains the following column names for the header section.

Column Name Description
Catalog Name The name of the catalog.
Catalog Id The ID of the catalog.
Store Id The ID of the store that contains the catalog.
Upload Time Do not use. If this field exists, ignore it.

The second row contains the header data. The third row is blank.

The fourth row contains the following column names for the report body, which starts on the fifth row.

Column Name Description
Item Id The offerId of the offer that failed validation or editorial review. The report will contain unique IDs.
Message The error being reported.
Type The type of error. The possible values are Error or Warning.
Values The data value that caused the error, if the error was caused by an invalid value.
Offer Snippet A semicolon-delimited list of subset of the offer data. The format is title;productType;link;imageLink;price;salePrice;saleStartDate;saleEndDate. Not all errors will include all components.

For an example of the report, see Example Report.