REST API Integration

SFTP handles daily full catalog snapshots, while the REST API is used for real-time incremental updates during the day. This chapter covers the complete Product Feed REST API reference.

4.1 Authentication

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer api_key_123

API keys are assigned by OpenAI after the merchant receives partner approval.

4.2 Required HTTP Headers

Every API request must include the following headers:

Header	Required	Description	Example
`Authorization`	Yes	Bearer token authentication	`Bearer api_key_123`
`Content-Type`	Yes	Request body format	`application/json`
`Accept-Language`	Yes	Response language preference	`en-US`
`User-Agent`	Yes	Client identifier	`MyStore/1.0`
`API-Version`	Yes	API version number	`2025-09-12`
`Timestamp`	Yes	Request time (RFC 3339)	`2026-04-11T08:30:00Z`
`Idempotency-Key`	Recommended	Idempotency key	`req_abc123`
`Request-Id`	Recommended	Request trace ID	`trace_xyz789`

API Version: Currently uses 2025-09-12. The version number ensures forward compatibility of API behavior. Timestamp format: Must use RFC 3339 format, such as 2026-04-11T08:30:00Z or with a timezone offset.

4.3 Feeds Endpoints

Create a Feed

POST /product_feeds
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "target_country": "US"
}

Response:

{
  "id": "feed_abc123",
  "target_country": "US",
  "updated_at": "2026-04-11T08:30:00Z"
}

Query a Feed

GET /product_feeds/:id
Authorization: Bearer api_key_123
API-Version: 2025-09-12

Response: Returns a Feed object containing id, target_country, and updated_at.

4.4 Products Endpoints

List Products

GET /product_feeds/:feed_id/products
Authorization: Bearer api_key_123
API-Version: 2025-09-12

Returns all products under the specified Feed.

Upsert Products

PATCH /product_feeds/:feed_id/products
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12
Idempotency-Key: upsert_20260411_batch1

{
  "products": [
    {
      "id": "prod_001",
      "title": "Wireless Earbuds Pro",
      "variants": [
        {
          "id": "var_001_black",
          "title": "Wireless Earbuds Pro - Black",
          "price": {
            "amount": 9999,
            "currency": "USD"
          },
          "availability": {
            "status": "in_stock"
          }
        }
      ]
    }
  ]
}

PATCH semantics: Uses upsert logic. Products are matched by id:

If the ID already exists — update that product
If the ID does not exist — create a new product
Products not included in the request — remain unchanged (they are not deleted)

This differs from SFTP full snapshots. The API PATCH does not delete products that are not mentioned; it only affects products included in the request.

4.5 Promotions Endpoints

List Promotions

GET /product_feeds/:feed_id/promotions
Authorization: Bearer api_key_123
API-Version: 2025-09-12

Upsert Promotions

PATCH /product_feeds/:feed_id/promotions
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "promotions": [
    {
      "id": "promo_spring_2026",
      "title": "Spring Sale 20% Off",
      "status": "active",
      "benefits": [
        {
          "type": "percent_off",
          "percent_off": 20
        }
      ],
      "active_period": {
        "start_time": "2026-04-01T00:00:00Z",
        "end_time": "2026-04-30T23:59:59Z"
      }
    }
  ]
}

Promotion data can only be submitted via the REST API. SFTP file upload is not supported for promotions.

4.6 Error Handling

HTTP Status Code	Error Type	Description
400	invalid_payload	Request body is malformed or missing required fields
404	not_found	Feed or product does not exist

400 error example:

{
  "error": {
    "code": "invalid_payload",
    "message": "Missing required field: variants[0].id"
  }
}

404 error example:

{
  "error": {
    "code": "not_found",
    "message": "Feed feed_nonexistent not found"
  }
}

4.7 Idempotency

Request idempotency is achieved through the Idempotency-Key header. Repeated requests with the same key will not produce side effects.

PATCH /product_feeds/feed_abc123/products
Idempotency-Key: batch_20260411_001

Usage guidelines:

Generate a unique key for each logical batch
Safe to retry with the same key after network timeouts
Keys are typically composed of a business identifier + timestamp
Different batches must use different keys

4.8 Best Practices

Small-Batch Validation First

Before full automation, start with a small batch of approximately 100 products:

Create a Feed          -> POST /product_feeds
Upload ~100 products   -> PATCH /product_feeds/:id/products
Verify data accuracy   -> GET /product_feeds/:id/products
Scale to full catalog once confirmed

API and SFTP Coordination

Scenario	Method
Daily full sync	SFTP file upload
Real-time price changes	REST API PATCH
Inventory status updates	REST API PATCH
Immediate new product launch	REST API PATCH
Promotion creation and management	REST API PATCH (only method)

Header Checklist

Confirm the following headers are complete before every API call:

Authorization: Bearer your_api_key
Content-Type: application/json
Accept-Language: en-US
User-Agent: YourApp/1.0
API-Version: 2025-09-12
Timestamp: 2026-04-11T08:30:00Z
Idempotency-Key: unique_key_per_request
Request-Id: trace_id_for_debugging

Next chapter: Chapter 5: Promotions Management — Promotion object specification, discount types, and active periods

ACP file upload via SFTP integration guide ACP promotions and discount configuration

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

ACP product feed REST API reference

REST API Integration

4.1 Authentication

4.2 Required HTTP Headers

4.3 Feeds Endpoints

Create a Feed

Query a Feed

4.4 Products Endpoints

List Products

Upsert Products

4.5 Promotions Endpoints

List Promotions

Upsert Promotions

4.6 Error Handling

4.7 Idempotency

4.8 Best Practices

Small-Batch Validation First

API and SFTP Coordination

Header Checklist

​REST API Integration

​4.1 Authentication

​4.2 Required HTTP Headers

​4.3 Feeds Endpoints

​Create a Feed

​Query a Feed

​4.4 Products Endpoints

​List Products

​Upsert Products

​4.5 Promotions Endpoints

​List Promotions

​Upsert Promotions

​4.6 Error Handling

​4.7 Idempotency

​4.8 Best Practices

​Small-Batch Validation First

​API and SFTP Coordination

​Header Checklist

REST API Integration

4.1 Authentication

4.2 Required HTTP Headers

4.3 Feeds Endpoints

Create a Feed

Query a Feed

4.4 Products Endpoints

List Products

Upsert Products

4.5 Promotions Endpoints

List Promotions

Upsert Promotions

4.6 Error Handling

4.7 Idempotency

4.8 Best Practices

Small-Batch Validation First

API and SFTP Coordination

Header Checklist