shoprocketDocs
Get started
Reference

REST API

Two surfaces, one shape. Public endpoints are safe to call from the browser; private endpoints are authenticated with a secret key and run on your server.

Full reference is generated from OpenAPI

This page covers the API basics that stay stable across versions, plus the endpoint map. The complete request/response reference for each endpoint ships from our OpenAPI spec alongside the API. Endpoints marked Planned are part of the roadmap and not yet callable.

Introduction

The public API powers the widget and any custom storefront. The private API powers your dashboard and server-side integrations. Both speak JSON and share the same casing, error, pagination, and timestamp conventions - the differences are the base URL, the auth key, and what you're allowed to do.

Public
curl https://api.shoprocket.io/v3/public/pk_live_.../cart \
  -H "X-Cart-Token: any-random-string"
Private
curl https://api.shoprocket.io/v3/private/products \
  -H "Authorization: Bearer sk_live_..."

Base URLs

Public endpoints are scoped to a store via your publishable key in the path. Private endpoints identify the store via your secret key in the Authorization header. Endpoint paths below omit the base URL and key, e.g. GET /cart means GET /v3/public/{pk}/cart.

Base URLs
https://api.shoprocket.io/v3/public/{publishable_key}
https://api.shoprocket.io/v3/private

Authentication

Use a publishable key (pk_) for the public API and a secret key (sk_) for the private API. Public cart endpoints additionally require an X-Cart-Token header to identify the visitor session. See the authentication guide for full detail.

Headers
Authorization: Bearer {your_key}
X-Cart-Token: {visitor_cart_token}   # public cart endpoints only

Conventions

  • All request and response bodies are JSON; keys are camelCase.
  • Money is an object with a minor-unit amount, a currency, and a formatted string.
  • IDs are type-prefixed (prod_, ord_, cus_); timestamps are ISO 8601 UTC.
Money object
"total": {
  "amount": 4200,
  "currency": "USD",
  "formatted": "$42.00"
}

Errors

Errors use standard HTTP status codes and a consistent body with a machine-readable code.

Error
{
  "error": {
    "code": "cart_item_out_of_stock",
    "message": "That product is out of stock."
  }
}

Pagination

List endpoints are cursor-paginated. Pass ?limit and ?cursor; the response includes a nextCursor when more results exist.

Paged response
{
  "data": [ /* … */ ],
  "hasMore": true,
  "nextCursor": "cur_abc123"
}

Get store

GET/storePUBLIC

Returns the store's public profile: name, currencies, languages, and theme settings.

Response
{
  "id": "str_123",
  "name": "Acme Goods",
  "currencies": ["USD", "EUR"],
  "defaultCurrency": "USD"
}

Get cart

GET/cartPUBLICAuth

Returns the current cart for the supplied X-Cart-Token, creating an empty one if the token is new.

Response
{
  "id": "cart_123",
  "items": [],
  "total": { "amount": 0, "currency": "USD" }
}

Add item

POST/cart/itemsPUBLICAuth

Adds a product (and optional variant) to the cart.

FieldTypeDescription
productIdrequiredstringThe product to add.
variantIdstringA specific variant, if the product has options.
quantityintegerDefaults to 1.
Request
curl -X POST .../cart/items \
  -H "X-Cart-Token: 8f3c…" \
  -d '{ "productId": "prod_123", "quantity": 1 }'

Cart

PUT/cart/items/{id}PUBLIC

Change the quantity of a line item.

DELETE/cart/items/{id}PUBLIC

Remove a line item from the cart.

POST/cart/discountPUBLIC

Apply a discount code to the cart.

DELETE/cart/discountPUBLIC

Remove the applied discount.

POST/cart/estimatePUBLIC

Estimate tax and shipping before checkout.

GET/cart/shipping-optionsPUBLIC

Available shipping options for the cart's address.

POST/cart/shippingPUBLIC

Choose a shipping option.

GET/cart/checkoutPUBLIC

Read the current checkout state.

PUT/cart/checkoutPUBLIC

Save customer and address details.

POST/cart/checkout/submitPUBLIC

Place the order and start payment.

Customer auth

POST/customers/checkPUBLICPlanned

Check whether an email has an account.

POST/customers/verifyPUBLICPlanned

Exchange an auth token for a session.

POST/customersPUBLICPlanned

Create a customer account.

GET/customers/statusPUBLICPlanned

Whether the current visitor is signed in.

GET/customers/mePUBLICPlanned

The signed-in customer's profile.

PUT/customers/mePUBLICPlanned

Update the customer's profile.

GET/customers/me/ordersPUBLICPlanned

The customer's order history.

GET/customers/me/orders/{id}PUBLICPlanned

A single order for the customer.

POST/customers/logoutPUBLICPlanned

End the customer session.

Products

GET/productsPUBLIC

The catalogue, filterable and paginated.

GET/products/{id}PUBLIC

A single product with variants and media.

GET/products/{id}/reviewsPUBLIC

Reviews for a product.

POST/products/{id}/reviewsPUBLIC

Submit a product review.

Categories

GET/categoriesPUBLIC

All product categories.

GET/categories/{id}PUBLIC

A single category.

Tax & payments

POST/tax/calculatePUBLIC

Tax for a given basket and address.

GET/payment-methodsPUBLIC

Enabled payment methods for the store.

Conversations

POST/conversationsPUBLICPlanned

Open a storefront chat conversation.

GET/conversations/currentPUBLICPlanned

The visitor's active conversation.

GET/conversations/{id}/messagesPUBLICPlanned

Messages in a conversation.

POST/conversations/{id}/messagesPUBLICPlanned

Send a message from the visitor.

Feeds

GET/feeds/productsPUBLIC

Google/Meta product feed, one URL per platform and locale.

Products

GET/productsPRIVATEPlanned

All products, including drafts.

POST/productsPRIVATEPlanned

Create a product.

PATCH/products/{id}PRIVATEPlanned

Update a product.

DELETE/products/{id}PRIVATEPlanned

Delete a product.

PATCH/products/{id}/stockPRIVATEPlanned

Adjust inventory levels.

Orders

GET/ordersPRIVATEPlanned

All orders, filterable.

GET/orders/{id}PRIVATEPlanned

A single order.

POST/orders/{id}/fulfilPRIVATEPlanned

Mark an order fulfilled / shipped.

POST/orders/{id}/refundPRIVATEPlanned

Refund an order in full or part.

POST/orders/{id}/cancelPRIVATEPlanned

Cancel an order.

Customers

GET/customersPRIVATEPlanned

All customers.

GET/customers/{id}PRIVATEPlanned

A single customer.

PATCH/customers/{id}PRIVATEPlanned

Update a customer.

Webhooks

GET/webhooksPRIVATEPlanned

Registered webhook endpoints.

POST/webhooksPRIVATEPlanned

Register a webhook endpoint.

DELETE/webhooks/{id}PRIVATEPlanned

Remove a webhook endpoint.