CartistoDocs
⌕

Getting started

Make your first authenticated request against a store.

Base URL & versioning

All endpoints live under a versioned prefix on the store’s domain:

https://<store-domain>/api/v1/…

The v1 prefix is the API’s major version — breaking changes ship a new prefix, never a silent change to v1. See Platform versioning.

Authenticate

Machine-to-machine access uses a scoped API key the merchant creates (sk_…). Send it as a Bearer token:

curl https://acme.cartisto.app/api/v1/products \
  -H "Authorization: Bearer sk_xxxxxxxxxxxx"

The key both authenticates you and pins you to that one store. See Authentication.

Read the envelope

{
  "success": true,
  "message": "Products fetched successfully",
  "data": {
    "products": [ /* … */ ],
    "pagination": { "page": 1, "limit": 20, "total": 128, "pages": 7 }
  }
}

A list endpoint returns its rows under a resource-named key (products, orders, customers, …) alongside a pagination object — not a generic items/total. Check success, then read data. On failure you get success: false, a message, and a matching HTTP status (400, 401, 403, 404, 409, 429). See Conventions.

A minimal client

async function cartisto(path, init = {}) {
  const res = await fetch(`https://acme.cartisto.app/api/v1${path}`, {
    ...init,
    headers: {
      "Authorization": `Bearer ${process.env.CARTISTO_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = await res.json();
  if (!body.success) throw new Error(`${res.status}: ${body.message}`);
  return body.data;
}

const { products } = await cartisto("/products?limit=20");

Next