Get started with the data ingestion API

Use the data ingestion API to create and manage product data for your ecommerce catalog. Data includes products, product attribute metadata, prices books, and prices.

Data Ingestion API overview

The Data Ingestion API is a RESTful API that allows you to manage product and price data for commerce applications using Adobe Commerce Optimizer. It is designed for backend applications to send data directly to Commerce Optimizer for use with storefront services. All product and price data is stored in a single base catalog that can be filtered and configured to create custom catalogs using Adobe Commerce Optimizer. This approach reduces processing time and improves catalog performance, especially for merchants with large or complex product assortments.

Base URL

Send all Data Ingestion API requests to the following base URL:

https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}
Copied to your clipboard
https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}

The URL structure is:

https://{{region}}-{{environment}}.api.commerce.adobe.com/{{tenantId}}

region is the cloud region where your instance is deployed.
environment-type is present only for non-production,sandbox environments.
tenantId is the unique identifier for your organization's specific instance within the Adobe Experience Cloud.

Sandbox instances can only be created in the North America region.

Get your endpoint URL and tenant ID

From Cloud Manager, you can find the endpoint URLs and tenant ID (instance ID) in the instance details for your Commerce Optimizer project.

Log in to your Adobe Experience Cloud account.
Under Quick access, click Commerce to open the Commerce Cloud Manager.
The Commerce Cloud Manager displays a list of instances that are available in your Adobe IMS organization.
To get the base URLs and instance ID, click the information icon next to the Adobe Commerce Optimizer instance name.

If you don't have access to Cloud Manager, you can also find the region and tenant ID from the access URL for the Adobe Commerce Optimizer application interface.

Header parameters

Include the following headers in REST API requests.

Header name	Required	Description
`Content-Encoding`	No	Use this header only if the payload is compressed with gzip. Accepted value: `gzip`.
`Content-Type`	Yes	Media type of the resource. Accepted value: `application/json`.
`Authorization: {{accessToken}}`	Yes	Bearer access token generated using credentials from the Adobe developer project for the API integration. See Authentication.

Request template

Use the following template to submit requests using curl replacing the placeholders as required.

curl --request POST \
  --url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/{{endpoint}} \
  --header "Content-Type:  application/json" \
  --header "Authorization: {{accessToken}}" \
  --data "{{apiPayload}}"
Copied to your clipboard
curl --request POST \
  --url https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/{{endpoint}} \
  --header "Content-Type:  application/json" \
  --header "Authorization: {{accessToken}}" \
  --data "{{apiPayload}}"

Placeholder name	Description
`endpoint`	Endpoint for specific Data Ingestion API, for example: `/v1/catalog/products/prices`
`accessToken`	Bearer token generated from IMS credentials. See Authentication.
`apiPayload`	API payload see examples in the tutorial

For sample requests, see the tutorial.

Use the Try It feature in the API reference to test API requests directly from your browser. For details, see Test API operations.

Make your first request

To get started with the Data Ingestion API, follow these steps to make your first request.

Generate an access token for the Authorization: {{accessToken}} header.

Submit your first request

Use the curl command line tool to submit a request to the Data Ingestion API.
Use the following endpoint to create the required product metadata for a catalog source (locale):

curl -X POST \
  'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/v1/catalog/products/metadata' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {{accessToken}}' \
  -d '[
    {
      "code": "sku",
      "source": {
        "locale": "en"
      },
      "label": "Product Name",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": true,
      "sortable": false,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "name",
      "source": {
        "locale": "en"
      },
      "label": "Product Name",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": false,
      "sortable": true,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "description",
      "source": {
        "locale": "en"
      },
      "label": "Product Description",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL"
      ],
      "filterable": false,
      "sortable": false,
      "searchable": false,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "shortDescription",
      "source": {
        "locale": "en"
      },
      "label": "Product Short Description",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL"
      ],
      "filterable": false,
      "sortable": false,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "price",
      "source": {
        "locale": "en"
      },
      "label": "Price",
      "dataType": "DECIMAL",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": true,
      "sortable": true,
      "searchable": false,
      "searchWeight": 1,
      "searchTypes": []
    }
  ]'
Copied to your clipboard
curl -X POST \
  'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/v1/catalog/products/metadata' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {{accessToken}}' \
  -d '[
    {
      "code": "sku",
      "source": {
        "locale": "en"
      },
      "label": "Product Name",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": true,
      "sortable": false,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "name",
      "source": {
        "locale": "en"
      },
      "label": "Product Name",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": false,
      "sortable": true,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "description",
      "source": {
        "locale": "en"
      },
      "label": "Product Description",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL"
      ],
      "filterable": false,
      "sortable": false,
      "searchable": false,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "shortDescription",
      "source": {
        "locale": "en"
      },
      "label": "Product Short Description",
      "dataType": "TEXT",
      "visibleIn": [
        "PRODUCT_DETAIL"
      ],
      "filterable": false,
      "sortable": false,
      "searchable": true,
      "searchWeight": 1,
      "searchTypes": [
        "AUTOCOMPLETE"
      ]
    },
    {
      "code": "price",
      "source": {
        "locale": "en"
      },
      "label": "Price",
      "dataType": "DECIMAL",
      "visibleIn": [
        "PRODUCT_DETAIL",
        "PRODUCT_LISTING",
        "SEARCH_RESULTS",
        "PRODUCT_COMPARE"
      ],
      "filterable": true,
      "sortable": true,
      "searchable": false,
      "searchWeight": 1,
      "searchTypes": []
    }
  ]'

Verify the response
- If the request is successful, you receive a 200 Created response with the metadata for the product attributes.
- If the request fails, you receive an error message with details about the issue.

Next steps

After you successfully make your first request, you can continue to use the Data Ingestion API to manage product and price data for your commerce catalog. The next steps include:

Create product metadata to define the attributes and behavior of your products.
Create products to add items to your catalog.
Create price books to manage pricing for different customer segments, regions, or sales channels.
Create prices to set the monetary values for your products within the price books.

You can also explore the API reference for detailed information about each endpoint and its parameters.

Create integrations with SDK

The Adobe Commerce Optimizer SDKs simplify integration with the Data Ingestion API by providing pre-built methods for catalog ingestion and IMS authentication. The SDKs handle the complexity of API interactions, allowing you to focus on your business logic.

Use the following GitHub repository links to download an available SDK and learn how to use it.

TypeScript SDK – for JavaScript/TypeScript integrations
Java SDK – for Java-based integrations

Limitations

The Data Ingestion API has a rate limit of 300 requests per minute. If you exceed the limit, the API returns a 429 response.

For additional information about limits and boundaries, see the Limits and boundaries section in the Adobe Commerce Optimizer Guide.

This guide covers direct API access using bearer tokens. For user authentication workflows, see the User Authentication in the Adobe Commerce REST Guide.

Authentication

Test API operations