Manage your store via API

Authentication and permissions

Authorization: Bearer <token>

• a staff user’s token: obtained with POST /auth/login and renewed with the rotating refresh (see Authentication). For staff accounts, reusing a superseded refresh token closes the session: don’t share it across processes.
• an API token: the recommended credential for integrations and long-running agents. It’s used as a Bearer, with no login or refresh, has a chosen role and a mandatory expiry (from 1 to 365 days), and can be revoked instantly. An administrator generates it, if the feature is enabled for the store (GET /admin/api-tokens/status; otherwise 403 tenant_keys.admin_api_disabled).

curl -X POST "$BASE/api/v1/admin/api-tokens" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"label":"ERP sync","role":"catalog_manager","expires_in_days":90}'
# data.token is shown only once: keep it like a secret.
# Revoke: POST /admin/api-tokens/{id}/revoke

Rules that matter to integrators

Money: who can do what

Owner, staff users, and API tokens

• Every store has one owner: an active administrator, recorded and stable, who doesn’t change when another account is promoted. GET /auth/me and the user list mark them with is_owner: true. Only Vellaro support can change the owner.
• The owner is protected: password, role, deactivation, deletion, and 2FA reset on their account answer 403 user.owner_protected. On the other administrators, the same actions can only be done by the owner (403 user.owner_only). An action that would leave the store without active administrators gives 409 user.last_admin.
• An API token doesn’t manage users or credentials: creating, editing, or deleting staff users, resetting their 2FA, generating or revoking API tokens and publishable keys answers 403 auth.api_token_forbidden. Reads stay allowed.

Orders, refunds, and returns

• Status transitions are validated: one that isn’t allowed gives 409 order.invalid_transition.
• comment is an internal note by default; with comment_public: true the customer also sees it in their history.
• A full refund or the cancellation of a paid order also gives back the part paid with a gift voucher. Stock is restocked only once.
• Returns start from an order line: GET /admin/returns/order-context/{order_id} lists the lines with their returnable quantities, then POST /admin/returns. A variant outside the order or a quantity beyond what’s returnable gives 422 return.item_not_in_order / return.quantity_exceeds_order. Return reasons and statuses are a shared, read-only catalog (403 return.lookup_global on writes).

curl -X POST "$BASE/api/v1/admin/orders/<id>/refunds" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"amount":"20.00","reason":"Damaged item","restock":true,"notify_customer":true}'
# → { "data": { "transaction": {...}, "payment_status": "partially_refunded",
#               "amount_refunded": "20.00", "restocked": false } }

Catalog and pricing

curl -X POST "$BASE/api/v1/admin/products" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{
    "name": "Como 3-seater sofa",
    "slug": "como-3-seater-sofa",
    "category_id": "<category uuid>",
    "is_active": true,
    "variants": [
      { "sku": "COMO-3P-GREY", "name": "Grey", "price": "1299.00", "stock": 5 },
      { "sku": "COMO-3P-BLUE", "name": "Blue", "price": "1299.00", "stock": 2 }
    ]
  }'

• Special prices and quantity discounts (/admin/products/{id}/specials, /discounts): the price must be greater than zero, otherwise 422 product.price_rule_not_positive. A special applies to everyone (customer_group_id: null) or to an active customer group, within its date window; among several specials the lowest priority wins, then the lowest price. A special can only lower the price, and cart and checkout apply it.
• Sale on a variant: sale_price, sale_start, and sale_end go together (422 product.sale_window_invalid if the window is invalid); to remove it, send all three as null.

Coupons and gift vouchers

• Coupons are validated on create and update: 422 coupon.percentage_out_of_range, coupon.negative_discount, coupon.dates_inverted; 409 coupon.code_taken. The list has a status filter (active, scheduled, expired, exhausted, inactive).
• DELETE /admin/coupons/{id} really deletes a coupon that was never used (the code becomes free again) and deactivates one already used: read deleted and deactivated in the response.
• Gift vouchers (/admin/vouchers, marketing permission): code, amount, and balance. The balance is spent at checkout (voucher_code), with amount_spent, redemption_count, and the history in GET /admin/vouchers/{id}/history. Here too DELETE only deletes a voucher that was never spent and deactivates it otherwise.

Subscriptions and recurring plans

{
  "name_i18n": { "en": "Monthly top-up", "it": "Ricarica mensile" },
  "price": "9.90", "frequency": "month", "duration": 1, "cycle": 12,
  "trial_status": true, "trial_frequency": "day", "trial_duration": 14,
  "is_active": true
}

Customers and affiliates

curl -X POST "$BASE/api/v1/admin/customers/<id>/anonymize" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{"confirm_email":"customer@example.com"}'

• Deactivating a customer (PATCH /admin/customers/{id} with is_active: false) closes all their sessions at once.
• Affiliate commissions (/admin/affiliate-commissions): readable with customers; approving, marking as paid, or rejecting also requires reports. The summary (/summary) has one row per affiliate and currency: currencies are never added together.

Reports

• An order counts as revenue if it’s collected (paid or partially_refunded, not refunded); the amount is the net, total minus refunded.
• The main figures are in the store’s base currency (the currency field); revenue in other currencies is kept separately in other_currencies.
• “Today”, days, and months follow the store’s time zone, returned in timezone.

Store settings

curl -X PUT "$BASE/api/v1/admin/settings" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{
    "group": "orders", "store_id": null,
    "settings": [
      { "key": "guest_checkout_allowed", "value": "false" },
      { "key": "min_order_total", "value": "20.00" }
    ]
  }'

Examples

# list products (includes inactive ones, for management)
curl "$BASE/api/v1/admin/products?page=1&page_size=24" -H "Authorization: Bearer $STAFF"

# orders + status change (with validated transitions)
curl "$BASE/api/v1/admin/orders?status=pending" -H "Authorization: Bearer $STAFF"
curl -X PATCH "$BASE/api/v1/admin/orders/<id>" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "status":"processing" }'

Best practices

• Errors: switch on error_code. A 403 plan.required means the feature isn’t included in the store’s plan: don’t retry.
• Idempotency & bulk: for mass updates (prices, stock), process in batches and handle 409/422 responses per row.
• Audit: every admin mutation is recorded in the store’s audit log.
• Soft-delete: deleting a product sets deleted_at (it doesn’t destroy the order history); deactivating is a different thing (is_active).
• Webhooks: to react to events without polling, use webhooks.
• Versioning: the API lives under /api/v1 — backward-compatible changes; breaking changes will go into a new version.