Placing Orders on a House Account

Use Checkout v2 to place orders for a brand whose orders are billed to its house account. You search the catalog, get delivery options for the recipient's address, create a checkout to lock in the price, then complete it. No card is collected: AccelPay invoices the brand for the full order total, and retailers are paid as usual.

📘

Your AccelPay contact enables house-account billing on the brand and gives you its brand ID ($BRAND_ID below) and your client ID and secret. Every request below, except getting a token, goes to https://api.accelpay.io.

1. Authenticate

Exchange your client ID and secret for an access token at AccelPay's auth server:

curl -X POST https://auth.accelpay.io/api/auth/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://unity.accelpay.io \
  --data-urlencode "scope=partner_checkout search:read"

The response's access_token works for both search and checkouts. Send it as Authorization: Bearer <token>.

The token is valid for expires_in seconds. Reuse it until it expires, then request a new one; don't request a token per call. The token is tied to your brand, so you can only search and place orders for that brand.

2. Find products

Search the catalog with a text query, filters, or both. Send {} to browse everything the brand can sell.

curl -X POST https://api.accelpay.io/v1/catalog/search \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "gin", "filters": {"sizes": ["750ml"], "availability": "in_stock"}, "pageSize": 24}'

Each product lists its variants. Keep the variantId of the size the customer picks; that is what you order. IDs are strings: pass them through unchanged rather than converting them to numbers. Use facets to build filters, and send nextPageToken back with the same query and filters to get the next page.

🚧

priceInfo is a price range across retailers, not a quote, and in_stock doesn't guarantee delivery to a given address. The checkout in step 4 sets the real price.

3. Get delivery options

Get delivery options for the items and the recipient's address. Pass estimateVariants as a URL-encoded JSON array. This endpoint is public and needs no token.

curl -G https://api.accelpay.io/v1/brands/$BRAND_ID/fulfillment-estimate \
  --data-urlencode 'estimateVariants=[{"variantId":123,"quantity":2}]' \
  --data-urlencode 'address=1 Main St' \
  --data-urlencode 'city=New York' \
  --data-urlencode 'state=NY' \
  --data-urlencode 'zip=10001'

Each option has a title, a delivery price, and a fulfillmentOptionId. Let the customer choose one and keep its fulfillmentOptionId.

4. Create a checkout

Create a checkout with the items, the buyer, the address, and the chosen delivery option. Send a unique Idempotency-Key for each order, such as a UUID.

curl -X POST https://api.accelpay.io/v1/brands/$BRAND_ID/partner-checkouts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1d2c4e-0f6a-4c55-9a51-3e2f1d9b8a10" \
  -d '{
    "line_items": [{"variant_id": "123", "quantity": 2}],
    "buyer": {"email": "[email protected]", "first_name": "Ada", "last_name": "Lovelace"},
    "fulfillment_address": {"line_one": "1 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US"},
    "fulfillment_option_id": "9-standard"
  }'

The response's totals is the price you'll be billed, in cents: items, delivery, tax, fees, and total. Show it to the customer before you complete.

• Retries are safe. The same request with the same key returns the same checkout (200 instead of 201).
• Use one key per order. A 409 means the key was already used for a different request, or its order was already placed. Check whether you already completed that order before retrying: a new key creates a new order.
• Checkouts can't be edited. To change the order, create a new checkout with a new key.
• Checkouts expire. Complete within 7 days. After that the checkout returns 404 and you need a new one.

5. Place the order

Complete the checkout with an empty body.

curl -X POST https://api.accelpay.io/v1/brands/$BRAND_ID/partner-checkouts/$CHECKOUT_ID/complete \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The checkout's status becomes completed and the response includes brand_sale_id, the order ID. Retrying a completed checkout returns the same order.

Orders appear in the AccelPay portal. When the response includes order_url, an order status page, you can share it with the customer.

If a price or tax changed since you created the checkout, completion fails with 400 and nothing is ordered. Create a new checkout to get the new total.

Errors

Checkout errors use this shape:

{"error": {"type": "invalid_request", "message": "buyer is required", "param": "buyer"}}

Search returns 401 for a missing or expired token, 403 when the token lacks the search:read scope, and 503 when search is temporarily unavailable.