Getting started

Learn how to make Product Admin APIs requests.

Asynchronous and synchronous calls

The Commerce API suite uses both asynchronous and synchronous calls. The product management APIs send asynchronous API requests to Global Commerce when:

• Creating, updating, deploying, retiring, or deleting a base or individual product

• Adding, updating, or deleting a product variation

• Deleting a base or individual product's locale

All other API requests are synchronous and return data immediately.

Asynchronous calls allow you to send multiple requests in a small timeframe without waiting for the completion of a request or worrying about timeouts. These calls are sent to Global Commerce to process product requests. Most products will complete successfully within a few seconds. However, creating or updating a base product with many variations and locales will take longer. For example, creating a base product with ten variations and 55 locales will take 30 seconds to a minute to complete.

When Global Commerce receives an asynchronous request, it returns a task identifier (taskId) in the response and puts the request in a queue. You can use the taskId in synchronous requests to retrieve product information and get the current status of a product.

Step 1: Obtain API credentials

When you get your credentials, ensure your API keys have permission to use the Admin APIs.

Step 2: Manage your products

Steps marked with Async below indicate the request goes to Global Commerce, where it is added to a queue. The remaining steps are synchronous and applied immediately.

1. Get your confidential key (secret). You will need the private key to send calls to the Admin APIs.

2. Async. Create a new product. You can create an individual product, a base product, or a product with variations.

3. Verify the successful completion of the task when creating or updating a product. Note: You cannot apply additional changes to the product until the system completes the previous task.

4. Choose one of the following options:

   • Async (deployment needed). Update a base product or individual product. You can update any supported attribute for a base or individual product. The change is visible to the shopper on the next deployment.

   • Async (deployment needed). Add or update a product variation. You can add or edit any supported attribute for a product variation. The change is visible to the shopper on the next deployment.

   • Async (live change). Apply a live change to an individual product, base product, or product variation. Update any supported attribute for an individual product, base product, or product variation. The change is visible to the shopper immediately upon completing the request.

   • Async. Delete a specific locale or delete a product variation. Update any supported attribute for an individual product or base product or remove a product variation. The change is visible to the shopper immediately upon completing the request.

5. Sync. Query tasks by task identifier, product identifier, or ERID. If you are using ERID, note that the request searches for tasks currently associated with the ERID. Note: Ensure all create and update requests are completed successfully or failed. You cannot deploy or retire a product before the task is completed.

6. Async. Deploy the product.

7. Async. Retire the product.

Step 3: Retrieve product information

The following steps are synchronous and applied immediately.

Choose one or more of the following options:

• Sync. Get product information. The response only returns supported attributes. All product variations (if any) for a base product will appear as a URL in the response.

• Sync. Get product information limited to a single locale. The response only returns supported attributes. All product variations (if any) for a base product will appear as a URL in the response.

• Sync. Get product variation information. The response only returns supported attributes.

• Sync. Get product variation information limited to a single locale. The response only returns supported attributes. The localizations object will only display information for the locale specified in the URL path.