Skip to main content

​
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:
HeaderRequiredDescriptionExample
AuthorizationYesBearer token authenticationBearer api_key_123
Content-TypeYesRequest body formatapplication/json
Accept-LanguageYesResponse language preferenceen-US
User-AgentYesClient identifierMyStore/1.0
API-VersionYesAPI version number2025-09-12
TimestampYesRequest time (RFC 3339)2026-04-11T08:30:00Z
Idempotency-KeyRecommendedIdempotency keyreq_abc123
Request-IdRecommendedRequest trace IDtrace_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 CodeError TypeDescription
400invalid_payloadRequest body is malformed or missing required fields
404not_foundFeed 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: 
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

ScenarioMethod
Daily full syncSFTP file upload
Real-time price changesREST API PATCH
Inventory status updatesREST API PATCH
Immediate new product launchREST API PATCH
Promotion creation and managementREST 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