Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt

Use this file to discover all available pages before exploring further.

This walks you through three calls: verify your key, create one product, and check a job status. By the end you will have a working curl command and a clear path to scale up to full catalog sync.

​
1. Get an API key

Follow the steps in Authentication to generate a key from Settings → Integrations. Export it for the rest of this page: 
export RETAILGRID_API_KEY="rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
2. Verify the key works

curl https://clientapi.retailgrid.io/v1/auth/verify \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
A 200 with "ok": true means you are good to go.

​
3. Create one product

Pick a product id you control - it is the stable identifier you will use to update or delete this product later. UUIDs are fine, but any string works. 
PRODUCT_ID="11111111-2222-3333-4444-555555555555"

curl -X POST "https://clientapi.retailgrid.io/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "SKU-DEMO-001",
    "product_name": "Demo running shoe",
    "brand": "Acme",
    "manufacturer": "Acme Footwear",
    "product_type": "shoe",
    "status": "active"
  }'
A 201 Created response returns the full product record, including the internal id Retailgrid assigned.

​
4. Bulk-upsert many products at once

For more than a handful of records, prefer /bulk. It accepts up to a few thousand items in one request and returns per-item results. 
curl -X POST "https://clientapi.retailgrid.io/v1/products/bulk" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": "SKU-DEMO-002", "product_name": "Demo trail shoe", "brand": "Acme"},
      {"product_id": "SKU-DEMO-003", "product_name": "Demo road shoe",  "brand": "Acme"}
    ]
  }'
The response has one BulkItemResult per input row, so partial failures do not block the whole batch. See Conventions for details.

​
5. Async CSV uploads

For full-catalog refreshes, use the CSV import endpoints. They return immediately with a job_id: 
curl -X POST "https://clientapi.retailgrid.io/v1/imports/products" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -F "file=@products.csv"

{ "job_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" }
Then poll for status: 
curl "https://clientapi.retailgrid.io/v1/jobs/0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
When "status": "completed", the data is live in your Retailgrid grids.

​
What’s next

  • Imports vs bulk - decide which endpoint family fits your pipeline.
  • Conventions - the patterns every endpoint follows.
  • Errors - what 422 responses look like and how to fix them.