Quickstart

This guide makes five requests with curl. It uses these shell variables:

export ONEBASKET_API_URL="https://your-storefront-api-host"   # base URL for your store
export ONEBASKET_API_KEY="your-api-key"                        # API key for your store

Your Stadion technical contact provides both values. See Environments.

Search for products

Call Search products. The x-api-key header is required on every request.

curl "$ONEBASKET_API_URL/catalogues/products?page=1&pageSize=10" \
  -H "x-api-key: $ONEBASKET_API_KEY" \
  -H "Accept-Language: en"

The response contains a results array of products, plus page, pageSize and totalResults. Copy the id of one product for the next steps.

Create a basket

Call Create a basket. The request has no body.

curl -X POST "$ONEBASKET_API_URL/baskets" \
  -H "x-api-key: $ONEBASKET_API_KEY"

The response is the new basket. Copy its id.

Add the product to the basket

Call Add a product to a basket. quantity is the only required field in the body.

curl -X POST "$ONEBASKET_API_URL/baskets/$BASKET_ID/products/$PRODUCT_ID" \
  -H "x-api-key: $ONEBASKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 1 }'

This request is asynchronous, because OneBasket has to update the basket in the provider's system. The response contains a notification id, not the updated basket:

{ "notificationId": "..." }

Wait for the result

Call Get a notification until status is no longer pending.

curl "$ONEBASKET_API_URL/notifications/$NOTIFICATION_ID" \
  -H "x-api-key: $ONEBASKET_API_KEY"

{ "status": "complete", "payload": { } }

status is pending, complete or failed. When it is complete, call Get a basket to read the updated basket. See Asynchronous operations for a polling example.

Start payment

Call Create a payment intent when the customer is ready to pay.

curl -X POST "$ONEBASKET_API_URL/baskets/$BASKET_ID/payment-intents" \
  -H "x-api-key: $ONEBASKET_API_KEY"

The basket is now immutable. The response is either a payment intent (200) or a notification id (202). You then take payment with the payment provider configured for your store. See Checkout flow.

Next steps

Authentication explains when a bearer token is required as well as the API key.
Checkout flow covers the full path from basket to order.
The API reference documents every endpoint. Each endpoint page can send a test request from the browser.