API referencev1

GET/me

Key: any valid key · No permission needed

Tells you which store a key belongs to, what the key may do and its rate limit. Make this your first call.

curl https://sitesplaced.com/api/v1/me \
  -H "Authorization: Bearer sp_live_sk_…"

{
  "api_version": "v1",
  "store": {
    "id": "uuid",
    "name": "Asha Jewels",
    "slug": "asha-jewels",
    "url": "https://asha-jewels.sitesplaced.site",
    "tracking_url": "https://asha-jewels.sitesplaced.site/track-order",
    "currency": "INR",
    "mode": "full"
  },
  "key": { "kind": "secret", "scopes": ["orders:read"], "connection_id": null },
  "limits": { "requests_per_minute": 60 }
}

store.mode is full for an ordinary SitesPlaced store, or tracking_only for a connected store whose public address shows only the tracking page. key.connection_idis set when the key is a plugin's connection key.

GET/orders

Key: secret · Permission: orders:read

Lists the store's orders, newest first, in the list envelope.

curl "https://sitesplaced.com/api/v1/orders?status=confirmed&updated_since=2026-09-18T00:00:00Z&limit=50" \
  -H "Authorization: Bearer sp_live_sk_…"

{
  "data": [ { …order object… }, { …order object… } ],
  "has_more": true,
  "next_cursor": "…"
}

POST/orders

Key: secret · Permission: orders:write

Creates an order or updates the one with the same external_id. The body, the rules and the response are described under Sending an order in.

Errors: 400 invalid_request when external_id or totals.total is missing or bad, with param naming the field. 413 payload_too_large when the body is over 1 MB.

POST/orders/batch

Key: secret · Permission: orders:write

Up to 50 orders in one call. See Batches.

GET/orders/{id}

Key: secret · Permission: orders:read

Returns one order. id is the SitesPlaced order id (a uuid), not the order number. To find an order by its id on the other platform, use GET /orders?external_id=.

curl https://sitesplaced.com/api/v1/orders/0b8c…uuid \
  -H "Authorization: Bearer sp_live_sk_…"

{ "order": { …order object… } }

An id that is not in this store gives 404 not_found.

PATCH/orders/{id}

Key: secret · Permission: orders:write

Changes the status, the tracking details, or both. Send any of the three fields: status, tracking and comment.

curl -X PATCH https://sitesplaced.com/api/v1/orders/0b8c…uuid \
  -H "Authorization: Bearer sp_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "tracking": { "number": "AWB123", "courier": "Delhivery", "url": "https://…" },
    "comment": "Dispatched"
  }'

{ "order": { …order object… } }

DELETE/orders/{id}

Key: secret · Permission: orders:write

Archives the order. It is not deleted: it drops out of GET /orders unless you ask with include_archived=true.

curl -X DELETE https://sitesplaced.com/api/v1/orders/0b8c…uuid \
  -H "Authorization: Bearer sp_live_sk_…"

{ "id": "0b8c…uuid", "archived": true }

POST/external-products/batch

Key: connection key · Permission: products:write

Used by the WooCommerce plugin and the Shopify connector to send a connected shop's product list. These products are kept apart from the store's own products: they can never appear on a SitesPlaced storefront or be put in a SitesPlaced cart. Only a connection key is accepted. Send up to 100 products per call; external_id and name are required on each.

{
  "products": [
    {
      "external_id": "88",
      "name": "Silver hoop earrings",
      "sku": "HOOP-S",
      "price": 1400,
      "currency": "INR",
      "image_url": "https://…",
      "category": "Earrings",
      "stock": 12
    }
  ]
}

{
  "results": [
    { "external_id": "88", "ok": true },
    { "external_id": "89", "ok": false, "error": "…" }
  ]
}

DELETE/external-products/{external_id}

Key: connection key · Permission: products:write

Removes one copied product, by its id on the other platform. Call it when the product is deleted there.

{ "external_id": "88", "deleted": true }

GET/products

Key: secret or publishable · Permission: products:read

Lists the store's own products, for a headless site. The store must be published. Prices are the ones the storefront shows. Query: limit, cursor and category.

curl "https://sitesplaced.com/api/v1/products?category=Earrings&limit=25" \
  -H "Authorization: Bearer sp_live_pk_…"

{
  "data": [ { …product object… } ],
  "has_more": false,
  "next_cursor": null
}

The product object:

{
  "id": "uuid",
  "object": "product",
  "name": "…",
  "description": "…",
  "price": 499,
  "compare_at_price": 699,
  "currency": "INR",
  "image_url": "https://…",
  "images": ["https://…"],
  "category": "Earrings",
  "categories": ["Earrings"],
  "type": "physical",
  "in_stock": true,
  "stock": 12,
  "variants": [
    { "options": { "Size": "M" }, "price": 499, "stock": 4, "sku": "SKU-M" }
  ],
  "url": "https://asha-jewels.sitesplaced.site/products/uuid"
}

GET/products/{id}

Key: secret or publishable · Permission: products:read

Returns one product by its id.

{ "product": { …product object… } }

GET/categories

Key: secret or publishable · Permission: products:read

Returns the store's category names. Pass one to GET /products?category=.

{ "data": ["Earrings", "Necklaces"] }

POST/checkout/sessions

Key: secret or publishable · Permission: checkout:write

Prepares a cart and returns a link to it. Send the shopper to url. The SitesPlaced cart opens with those lines already in it, and the shopper pays there.

curl -X POST https://sitesplaced.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer sp_live_pk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "product_id": "uuid", "quantity": 2, "variant": { "Size": "M" } }
    ],
    "return_url": "https://myshop.com/thanks"
  }'

{
  "url": "https://asha-jewels.sitesplaced.site/cart?restore=cl_…",
  "token": "cl_…",
  "expires_at": "…"
}

• Prices, stock, payment methods and every checkout guard are SitesPlaced's own. You send product ids and quantities, never prices.
• A cart can hold up to 50 lines.
• An unknown or archived product gives 422 unprocessable.
• With a publishable key, return_urlmust be on one of the key's allowed websites. This stops anyone who copies the key from using your checkout to send shoppers to a site of their choosing.
• The link works for 24 hours.

The whole flow is under The headless checkout.

GET/tracking

Key: secret or publishable · Permission: tracking:read

Looks up one order's status for a shopper. Query: order (the order number) and, for an order copied in from another platform, contact.

curl "https://sitesplaced.com/api/v1/tracking?order=1234&contact=6363" \
  -H "Authorization: Bearer sp_live_pk_…"

{
  "order": {
    "order_number": "1234",
    "status": "shipped",
    "items": [ … ],
    "total_amount": 1499,
    "shipping_fee": 99,
    "cod_fee": 0,
    "currency": "INR",
    "tracking_link": "https://…",
    "status_comment": "Dispatched",
    "shipping_awb": "AWB123",
    "shipping_courier": "Delhivery",
    "shipping_status_text": "In transit",
    "status_history": [ … ],
    "created_at": "2026-09-18T10:00:00.000Z",
    "updated_at": "2026-09-18T12:00:00.000Z"
  },
  "store": { "name": "Asha Jewels" }
}

• The response never contains a name, a phone number, an email or an address.
• An unknown order gives 404 not_found.
• An order copied in from another platform needs contact: the last 4 digits of the phone number on the order, or the email. If it is missing you get 422 with param: "contact". If it is wrong you get 422. Five wrong tries give 429 for 15 minutes.

{
  "error": {
    "code": "unprocessable",
    "message": "…",
    "param": "contact",
    "request_id": "req_…"
  }
}

Why the second detail exists is explained under Tracking and the second detail.

GET/webhooks

Key: secret · Permission: webhooks:write

Lists the store's webhook endpoints. The signing secret is never listed.

{
  "data": [
    {
      "id": "uuid",
      "url": "https://myshop.com/hooks/sitesplaced",
      "events": ["order.created", "order.shipped"],
      "active": true,
      "created_at": "2026-09-18T10:00:00.000Z"
    }
  ]
}

POST/webhooks

Key: secret · Permission: webhooks:write

Registers an address to receive events. url must be a public https address. The secret in the response is shown once: store it now, because you need it to check signatures.

curl -X POST https://sitesplaced.com/api/v1/webhooks \
  -H "Authorization: Bearer sp_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://myshop.com/hooks/sitesplaced", "events": ["order.created", "order.shipped"] }'

{
  "id": "uuid",
  "url": "https://myshop.com/hooks/sitesplaced",
  "events": ["order.created", "order.shipped"],
  "secret": "whsec_…"
}

The events and the delivery rules are under Webhooks.

DELETE/webhooks/{id}

Key: secret · Permission: webhooks:write

Removes a webhook endpoint. No more events are sent to it.

{ "id": "uuid", "deleted": true }

POST/connect/exchange

Key: none (a one-time code) · No permission needed

The last step of connecting a plugin: the plugin swaps the one-time code for its own key, server to server. No key is sent, because the plugin does not have one yet. The code works once, for 10 minutes, and only when the host of site_url matches the shop that was approved. A failure gives 400.

POST https://sitesplaced.com/api/v1/connect/exchange

{ "code": "spc_…", "site_url": "https://shop.example.com" }

{
  "api_key": "sp_live_sk_…",
  "webhook_secret": "whsec_…",
  "connection_id": "uuid",
  "store": {
    "id": "uuid",
    "name": "…",
    "slug": "…",
    "tracking_url": "https://…/track-order",
    "dashboard_url": "https://sitesplaced.com/sites/uuid/commerce/orders"
  }
}

The whole flow is under Connecting a plugin.

POST/connect/disconnect

Key: connection key · Permission: connection:manage

Closes the connection. The key stops working immediately afterwards. The orders already copied are kept.

{ "ok": true }

GET/connection

Key: connection key · Permission: connection:manage

The status of the connection this key belongs to. A plugin shows this on its own status screen.

{
  "connection": {
    "id": "uuid",
    "platform": "woocommerce",
    "status": "…",
    "status_detail": "…",
    "shop_url": "https://shop.example.com",
    "orders_synced": 128,
    "last_order_at": "2026-09-18T10:00:00.000Z"
  },
  "store": {
    "id": "uuid",
    "name": "…",
    "slug": "…",
    "tracking_url": "https://…/track-order",
    "dashboard_url": "https://sitesplaced.com/sites/uuid/commerce/orders"
  }
}

PUT/connection

Key: connection key · Permission: connection:manage

The plugin reports its version and the address SitesPlaced should send updates to. push_url may be nullwhen the shop's REST API cannot be reached; the plugin then relies on pulling.

{
  "plugin_version": "1.0.0",
  "platform_version": "…",
  "site_url": "https://shop.example.com",
  "push_url": "https://shop.example.com/wp-json/sitesplaced/v1/updates",
  "shop_name": "…",
  "currency": "INR"
}

GET/connection/updates

Key: connection key · Permission: connection:manage

Returns the updates waiting to go back to the shop. A plugin calls this every 15 minutes as a fallback, with ?limit=50.

{ "updates": [ { …update… } ] }

POST/connection/updates/ack

Key: connection key · Permission: connection:manage

The plugin reports which updates it applied and which failed, so they are not sent again.

{
  "applied": ["id"],
  "failed": [ { "id": "…", "error": "…" } ]
}

{ "acknowledged": 1 }

GET/openapi.json

Key: none · No permission needed

A machine-readable description of this API in the OpenAPI 3.1 format. No key is needed. Tools can read it to generate a client or to import the routes into an API testing app.

https://sitesplaced.com/api/v1/openapi.json