data-slots=text

data-backgroundColor=green

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}}

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.

data-variant=info

data-slots=text

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

Get your endpoint URL and tenant ID

data-src=../../includes/authentication/get-tenant-id.md

Header parameters

Include the following headers in REST API requests.

Header name

Required

Description

Content-Encoding

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}}"

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.

data-variant=note

data-slots=text

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": []
    }
  ]'

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.

Test API operations using Try it

Interactively explore and test Data Ingestion API operations using the Try it capability available in the Data Ingestion API reference.

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 using Adobe Commerce Optimizer SDKs

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.

data-variant=info

data-slots=text

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