Checkout and payment

All calls on this page need a customer token. Paths and shell variables are as in Before you start.

1. Claim the guest cart

Sign the customer in through the Auth API. Refer to Sign-in and Sign-up.

Then move the guest's parts and carts to the customer. Send the customer token as the Bearer token, and the guest token in the body:

curl -X PATCH "$API/cart/$CART_ID/claim" \
  -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d "{ \"anonymousSessionToken\": \"$GUEST_TOKEN\" }"

Response 204. One call moves all parts and all open carts of that guest to the customer.

After the claim, discard the guest token. From this point, use the customer token for all calls.

2. Select an address and shipping

# Addresses of the customer's organisation
curl "$API/address" -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN"

# Shipping methods of the store
curl "$API/operator/shipping-methods" -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN"

# Rates for delivery to an address
curl -X POST "$API/shipping/rate" \
  -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "toAddressId": 123,
    "parts": [
      { "partRevisionId": "…", "units": "MILLIMETERS", "quantity": 1, "processPricesId": "…", "materialId": 12 }
    ]
  }'

A shipping method has a shippingMode:

To create an address, refer to Addresses. For all shipping fields, refer to Shipping.

3. Get the final price

Call POST /pre-order again. This time, include shipping and billingAddressId. The quote then includes shipping and the correct tax.

4. Create the order

POST /order uses the same body as POST /pre-order, plus cartId and intent.

curl -X POST "$API/order" \
  -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{ …the pre-order body…, "cartId": "…", "intent": "CHECKOUT" }'

• The API calculates the price again. It does not trust a price from the client.
• The new order has "state": "QUOTE" and "paymentStatus": "UNPAID". It becomes an ORDER when the customer pays or accepts.
• If you give a cartId, the cart must be open. After the call, the cart status is CONVERTED.
• Send "intent": "CHECKOUT" when the customer continues to payment immediately. Without it, the customer gets a "your quote is ready" notification. Omit it for a "save as quote" button.

Response:

{
  "order": { "id": 4711, "state": "QUOTE", "paymentStatus": "UNPAID", "quoteNumber": "Q-1042", "price": 54.2, "currency": "EUR", "threadId": 880 },
  "requisitionMapping": { "7b0c1a52-0d1e-4b0c-8f5e-0c6a1c0f3e11": { "id": 9001, "orderId": 4711 } }
}

5. Check that the order can be paid

curl "$API/order/$ORDER_ID/purchasability" -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN"

If canBePurchased is false, the manufacturer must review the quote first.

6. Choose the payment methods

There are three ways to pay. Which ones you show depends on the store settings and on the customer type (GET /customer, field customerType).

7. Take the payment

curl -X POST "$API/order/$ORDER_ID/payment" -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN"

{
  "id": "pi_…",
  "provider": "STRIPE",
  "clientSecret": "pi_…_secret_…",
  "merchantAccount": "acct_…",
  "finalPrice": 54.2,
  "tax": 9.2,
  "currency": "EUR",
  "stripePaymentIntentStatus": "requires_payment_method"
}

curl -X PATCH "$API/order/$ORDER_ID/payment/invoice" -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN"

curl -X PATCH "$API/order/$ORDER_ID/payment/purchase-order" \
  -H "X-Store-Name: $STORE" -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -F "purchaseOrderNumber=PO-2026-118" -F "message=Please confirm the delivery date" -F "file=@po.pdf"

8. Follow the order

There is no push channel. Poll GET /order/{id} with a customer token.

More calls