Developers · Preview

Admin API reference

Apps installed on a store read and change its data over HTTPS and JSON. Installing apps opens soon; this reference describes version v1.

OpenAPI 3.1 document (import it into Postman, Insomnia or a code generator)

Basics

Base URL: https://api.storesdot.com/v1
Authentication: Send the installation’s access token, shown once when the store installs your app: Authorization: Bearer sza_…. Each token belongs to one store and carries the scopes the merchant granted; a write_ scope includes its read_ scope.
Rate limits: A leaky bucket per installation: 40 requests at once, refilling at 2 per second. Every response has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 carries Retry-After.
Pagination: Lists are newest first. Use limit (1–250) and follow the Link: <…>; rel="next" header; its page_info cursor is opaque.
Money: Integers in minor units (paisa for PKR), with the store’s currency.
Errors: Always { "error": { "code", "message", "request_id" } }, plus missing_scopes on a 403 and issues on a 422. Quote the request_id (also the X-Request-Id header) when you contact us.

Shop

GET /shop

The store the app is installed on

Scopes: none (any installation)

Parameters of getShop
Parameter	In	Description
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 429.

Products

GET /products

List products, newest first

Scopes: read_products

Parameters of listProducts
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /products

Create a product with its variants

Scopes: write_products

Returns object; errors 401, 403, 422, 429.

GET /products/{id}

One product with its variants

Scopes: read_products

Parameters of getProduct
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /products/{id}

Update a product; fields left out keep their value

Scopes: write_products

Parameters of updateProduct
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

DELETE /products/{id}

Delete a product

Scopes: write_products

Parameters of deleteProduct
Parameter	In	Description
id *	path	uuid

Returns Empty; errors 401, 403, 404, 429.

Collections

GET /collections

List collections, newest first

Scopes: read_products

Parameters of listCollections
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /collections

Create a manual or smart collection

Scopes: write_products

Returns object; errors 401, 403, 422, 429.

GET /collections/{id}

One collection (manual ones with their products)

Scopes: read_products

Parameters of getCollection
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /collections/{id}

Update a collection; fields left out keep their value

Scopes: write_products

Parameters of updateCollection
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

DELETE /collections/{id}

Delete a collection (its products stay)

Scopes: write_products

Parameters of deleteCollection
Parameter	In	Description
id *	path	uuid

Returns Empty; errors 401, 403, 404, 429.

Inventory

GET /locations

The store’s stock locations

Scopes: read_inventory

Parameters of listLocations
Parameter	In	Description
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 429.

GET /locations/{id}

One stock location

Scopes: read_inventory

Parameters of getLocation
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

GET /inventory_levels

Stock per variant and location (filter by location and / or variants)

Scopes: read_inventory

Parameters of listInventoryLevels
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
location_id	query	uuid
variant_ids	query	Comma-separated variant ids (at most 100).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /inventory_levels/adjust

Add to or take from available stock (send an Idempotency-Key)

Scopes: write_inventory

Returns object; errors 401, 403, 422, 429.

POST /inventory_levels/set

Set available stock to a count (send an Idempotency-Key)

Scopes: write_inventory

Returns object; errors 401, 403, 422, 429.

Orders

GET /orders

List orders, newest first

Scopes: read_orders

Parameters of listOrders
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

GET /orders/{id}

One order with its line items

Scopes: read_orders

Parameters of getOrder
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /orders/{id}

Change an order’s note and tags

Scopes: write_orders

Parameters of updateOrder
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

POST /orders/{id}/cancel

Cancel an open order (stock back unless restock is false)

Scopes: write_orders

Parameters of cancelOrder
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

POST /orders/{id}/close

Close (archive) an order

Scopes: write_orders

Parameters of closeOrder
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 429.

POST /orders/{id}/open

Reopen a closed order

Scopes: write_orders

Parameters of reopenOrder
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 429.

Fulfillments

GET /orders/{id}/fulfillments

An order’s fulfillments (parcels)

Scopes: read_fulfillments

Parameters of listFulfillments
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

POST /orders/{id}/fulfillments

Fulfil items with your own carrier and tracking (send an Idempotency-Key)

Scopes: write_fulfillments

Parameters of createFulfillment
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

POST /orders/{id}/fulfillments/{fulfillment_id}/cancel

Cancel a fulfillment (its items go back to unfulfilled)

Scopes: write_fulfillments

Parameters of cancelFulfillment
Parameter	In	Description
id *	path	uuid
fulfillment_id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

POST /orders/{id}/fulfillments/{fulfillment_id}/delivered

Mark a parcel delivered (own riders, or a courier that stopped reporting)

Scopes: write_fulfillments

Parameters of markFulfillmentDelivered
Parameter	In	Description
id *	path	uuid
fulfillment_id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

Refunds

GET /orders/{id}/refunds

An order’s refunds

Scopes: read_orders

Parameters of listRefunds
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

POST /orders/{id}/refunds

Refund items, shipping or an amount — online through the gateway when it can, or recorded as manual (send an Idempotency-Key)

Scopes: write_refunds

Parameters of createRefund
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

Customers

GET /customers

List customers, newest first

Scopes: read_customers

Parameters of listCustomers
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /customers

Create a customer (a phone number or an e-mail is required)

Scopes: write_customers

Returns object; errors 401, 403, 422, 429.

GET /customers/{id}

One customer

Scopes: read_customers

Parameters of getCustomer
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /customers/{id}

Update a customer; fields left out keep their value

Scopes: write_customers

Parameters of updateCustomer
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

Discounts

GET /discounts

List discounts, newest first

Scopes: read_discounts

Parameters of listDiscounts
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /discounts

Create a code or automatic discount

Scopes: write_discounts

Returns object; errors 401, 403, 422, 429.

GET /discounts/{id}

One discount

Scopes: read_discounts

Parameters of getDiscount
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /discounts/{id}

Replace a discount’s definition (and optionally its status)

Scopes: write_discounts

Parameters of updateDiscount
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

DELETE /discounts/{id}

Delete a discount that was never used (disable it otherwise)

Scopes: write_discounts

Parameters of deleteDiscount
Parameter	In	Description
id *	path	uuid

Returns Empty; errors 401, 403, 404, 429.

Pages

GET /pages

List pages, newest first

Scopes: read_content

Parameters of listPages
Parameter	In	Description
limit	query	Page size, 1–250 (default 50).
page_info	query	Opaque cursor from the previous response’s Link header.
updated_at_min	query	Only items changed at or after this time (ISO 8601).
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

POST /pages

Create a page

Scopes: write_content

Returns object; errors 401, 403, 422, 429.

GET /pages/{id}

One page

Scopes: read_content

Parameters of getPage
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.

PUT /pages/{id}

Update a page; fields left out keep their value

Scopes: write_content

Parameters of updatePage
Parameter	In	Description
id *	path	uuid

Returns object; errors 401, 403, 404, 422, 429.

DELETE /pages/{id}

Delete a page

Scopes: write_content

Parameters of deletePage
Parameter	In	Description
id *	path	uuid

Returns Empty; errors 401, 403, 404, 429.

Metafields

GET /metafields

An owner’s metafields (needs the read scope of the owner: products, customers, orders or content)

Scopes: none (any installation)

Parameters of listMetafields
Parameter	In	Description
owner_type *	query	string
owner_id *	query	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 422, 429.

PUT /metafields

Set an owner’s metafield values (needs the write scope of the owner)

Scopes: none (any installation)

Returns object; errors 401, 403, 422, 429.

POST /metafield_definitions

Make sure a metafield definition exists (idempotent; needs the write scope of the owner type)

Scopes: none (any installation)

Returns object; errors 401, 403, 422, 429.

Webhooks

GET /webhooks

This app’s webhook subscriptions in the store

Scopes: none (any installation)

Parameters of listWebhooks
Parameter	In	Description
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 429.

POST /webhooks

Subscribe to a topic (needs the read scope of the topic’s data)

Scopes: none (any installation)

Returns object; errors 401, 403, 422, 429.

DELETE /webhooks/{id}

Remove a subscription

Scopes: none (any installation)

Parameters of deleteWebhook
Parameter	In	Description
id *	path	uuid

Returns Empty; errors 401, 403, 404, 429.

Billing

GET /charges

This app’s charges in the store

Scopes: none (any installation)

Parameters of listCharges
Parameter	In	Description
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 429.

POST /charges

Ask the merchant to pay (one-time or monthly, PKR): send them to confirmation_url to approve; billed on their Stores. invoice

Scopes: none (any installation)

Returns object; errors 401, 403, 422, 429.

GET /charges/{id}

One of this app’s charges

Scopes: none (any installation)

Parameters of getCharge
Parameter	In	Description
id *	path	uuid
fields	query	Comma-separated top-level fields to return (id is always included).

Returns object; errors 401, 403, 404, 429.