ERP integration

Connect your ERP to the Admin API: create products with variants, adjust the stock of each one, and receive new orders.

Requirements

• An app with the From your server connection, with its client_id and client_secret on your server. See Quickstart.
• The catalog:create, inventory:read, and inventory:update permissions. The Full ERP template includes them.

Request a token

Request the token with client_credentials and the api_admin scope. The app is bound to the store, so the token already identifies it. Cache it and renew it before it expires.

curl -X POST https://auth.ecomiq.pe/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$ECOMIQ_CLIENT_ID" \
  -d "client_secret=$ECOMIQ_CLIENT_SECRET" \
  -d "scope=api_admin"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in is the lifetime in seconds. The next examples use getToken(). More detail in Authentication.

Create a product

Declare the options in options and one variant per combination in variants. Each variant sets its value for each option in options.

{
  "name": "Polo clásico",
  "description": "Polo unisex disponible en varios colores y tallas.",
  "status": "active",
  "isDigital": false,
  "options": [
    { "name": "Color", "key": "color", "values": ["Azul", "Blanco"] },
    { "name": "Talla", "key": "talla", "values": ["M", "L"] }
  ],
  "variants": [
    {
      "name": "Azul / M",
      "sku": "POL-CL-AZ-M",
      "price": 89,
      "trackInventory": true,
      "options": { "Color": "Azul", "Talla": "M" },
      "isDefault": true
    },
    {
      "name": "Blanco / L",
      "sku": "POL-CL-BL-L",
      "price": 89,
      "trackInventory": true,
      "options": { "Color": "Blanco", "Talla": "L" },
      "isDefault": false
    }
  ]
}

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  --data @product.json

The API responds 201 with the product and its variants. Store each variant id next to its SKU; IDs are strings. All fields are in Create a product.

Read the stock

POST /v1/inventory/levels returns the stock of the variants at each location. Each row has locationId, onHand, available, and version.

curl -X POST https://api.ecomiq.pe/api/v1/inventory/levels \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "variantIds": ["7204558912004325377"] }'

Your location IDs are in List locations.

Adjust the stock

Send the variant, the location, the quantity, and the reason. mode: "adjust" adds the quantity to the current stock; mode: "set" sets it. In expectedVersion, send the version you read, or 0 if the variant has no level at that location yet.

curl -X POST https://api.ecomiq.pe/api/v1/inventory/adjust \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "7204558912004325377",
    "locationId": "7204558912004325378",
    "target": "onHand",
    "mode": "adjust",
    "quantity": 5,
    "reason": "restock",
    "note": "Ingreso de cinco unidades.",
    "expectedVersion": 3
  }'

The response returns the level with its new version. If the version you sent has changed, the API responds 409 Inventory.Changed: read the stock again and retry. For many variants at once, use Update stock in bulk.

Receive orders

Subscribe an endpoint in your ERP to the order.created event. You get one for every new order. Follow Incoming orders.

Errors

Next steps

• Incoming orders: receive and verify every new order.
• Inventory: multiple locations, conflicts, and batches.
• Errors: formats and when to retry.