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:
Copied to your clipboardhttps://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.
Copied to your clipboardcurl --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
):
Copied to your clipboardcurl -X POST \'https://na1-sandbox.api.commerce.adobe.com/{{tenantId}}/v1/catalog/attributes/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.
- If the request is successful, you receive a
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.