> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP product feed REST API reference

> ACP Product Feed REST API complete reference — Feeds, Products, and Promotions endpoints with request examples and response schemas.

# 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:

```http theme={null}
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

```http theme={null}
POST /product_feeds
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "target_country": "US"
}
```

**Response**:

```json theme={null}
{
  "id": "feed_abc123",
  "target_country": "US",
  "updated_at": "2026-04-11T08:30:00Z"
}
```

### Query a Feed

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
GET /product_feeds/:feed_id/promotions
Authorization: Bearer api_key_123
API-Version: 2025-09-12
```

### Upsert Promotions

```http theme={null}
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"
      }
    }
  ]
}
```

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

## 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**:

```json theme={null}
{
  "error": {
    "code": "invalid_payload",
    "message": "Missing required field: variants[0].id"
  }
}
```

**404 error example**:

```json theme={null}
{
  "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.

```http theme={null}
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:

```
1. Create a Feed          -> POST /product_feeds
2. Upload ~100 products   -> PATCH /product_feeds/:id/products
3. Verify data accuracy   -> GET /product_feeds/:id/products
4. 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:

```http theme={null}
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](/en/book-4/ch5-promotions) — Promotion object specification, discount types, and active periods