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 identifies non-production environments, for example, sandbox or staging.
tenantId is the unique identifier for your organization's specific instance within the Adobe Experience Cloud.

Get your tenant ID

From Cloud Manager, you can find your tenant ID in the instance detailLs 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 tenant ID, click the information icon next to the Adobe Commerce Optimizer instance name.

The instance details page opens, displaying the tenant ID and other instance information. The tenant ID is displayed in the Instance ID field.

You can also find the tenant ID from the access URL for the Adobe Commerce Optimizer application interface, the value is in the path, for example /in:XDevkG9W6UbwgQmPn995r3/.

If you don't have access to the Commerce Cloud Manager, contact your system administrator.

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: Bearer {access token}`	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: Bearer {access token}" \
  --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: Bearer {access token}" \
  --data "{apiPayload}"

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

For sample requests, see the tutorial.

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: Bearer {access-token} 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/attributes/metadata' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access token}' \
  -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/attributes/metadata' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access token}' \
  -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 (ACO) SDK simplifies integration with the Data Ingestion API by providing pre-built methods for catalog ingestion and IMS authentication. The SDK handles the complexity of API interactions, allowing you to focus on your business logic. To download the SDK and learn how to use it, see the Adobe Commerce Optimizer GitHub repository.