Store API — options & variants

Manage your Southbill Store catalogue, option groups, variants, orders and evidence with your secret API key.

Store API — options & variants

Your Southbill Store catalogue is reachable with the same secret API key you use for the rest of the REST API. Base URL:

https://api.southbill.com/v1/store/v1

Authenticate with Authorization: Bearer sk_live_… (server-side only — secret keys are rejected from a browser origin). Write calls accept an Idempotency-Key header.

Required scopes: store:read, products:read, products:write, orders:read, orders:write, files:write. Existing keys were upgraded automatically.

Why variants

A product is the catalogue item ("Runner 01"). A variant is the concrete thing a buyer picks — Size M, Colour Black. Variants are built from option groups (Size) and option values (S, M, L). Each variant references exactly one value per option group and may carry its own price, SKU and stock.

Product "Runner 01"
├─ Option group "Size"   → values S, M, L
├─ Option group "Colour" → values Black, White
└─ Variants: S/Black (SKU RUN-S-BLK), M/Black, …

Endpoints

Method Path Description
GET /store The merchant's store (slug, display name, status, logo/cover URLs).
GET /products List products.
GET /products/{id} Product incl. option_groups and variants.
POST /products Create a product.
PATCH /products/{id} Update a product.
DELETE /products/{id} Archive a product.
POST /products/{id}/prices Create a price (min 250 minor units).
GET POST /products/{id}/options List / create option groups.
PATCH DELETE /options/{id} Rename / delete an option group.
POST /options/{id}/values Add a value to a group.
DELETE /values/{id} Delete an option value.
GET POST /products/{id}/variants List / create variants.
PATCH DELETE /variants/{id} Update / delete a variant.
GET /orders, /orders/{id} Store orders (source store only).
PATCH /orders/{id} Fulfillment updates — shipped/completed need evidence.
POST /orders/{id}/evidence Attach delivery evidence.
POST /files Upload product images, documents or evidence (max 5 MB).

Create an option group

curl https://api.southbill.com/v1/store/v1/products/PRODUCT_ID/options \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Size", "values": ["S", "M", "L"] }'

{
  "object": "option_group",
  "id": "8df0e320-…",
  "product": "019c72f4-…",
  "name": "Size",
  "values": [
    { "object": "option_value", "id": "9f7e71ab-…", "value": "S", "sort_order": 0 },
    { "object": "option_value", "id": "82170ba4-…", "value": "M", "sort_order": 1 }
  ]
}

Create a variant

curl https://api.southbill.com/v1/store/v1/products/PRODUCT_ID/variants \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: variant-run01-s-blk" \
  -d '{
    "options": [{ "group": "8df0e320-…", "value": "9f7e71ab-…" }],
    "price": "6040da6b-…",
    "sku": "RUN-S-BLK",
    "track_inventory": true,
    "stock_qty": 12
  }'

Rules enforced by the API:

  • options must contain exactly one value per option group of the product.
  • A value must belong to the group it is sent with (invalid_options, 400).
  • The same combination cannot exist twice (variant_exists, 409).
  • price must be an active price on the same product; omit it to inherit the product's default price.
  • stock_qty is required when track_inventory is true.
  • The option combination is immutable — delete and recreate the variant to change it.

Deleting

Deletion is guarded so your storefront never ends up with dangling variants:

  • DELETE /values/{id} → 409 value_in_use while a variant uses that value.
  • DELETE /options/{id} → 409 variants_exist while the product still has variants.
  • DELETE /variants/{id} works at any time, except for the implicit default variant of a product.

Sandbox

The identical routes exist in the sandbox through an installed app (App API, environment test). Sandbox writes never touch a payment provider — the catalogue, variants and orders live in isolated sandbox tables and are wiped on a sandbox reset.