Commerce guide

Tell Fendsy when an order is real.

Shopify supplies confirmed orders for Shopify stores. For a normal commerce website, your trusted server can confirm an order with a scoped key after your own checkout accepts it.

Before you send

  1. Create or identify the Customer Profile in the same workspace.
  2. Create active manual Catalog Items and Variants in the same currency as the order.
  3. Create a server key with orders:write. Add orders:read to inspect results.

A Site-scoped key can submit orders only for its Site. An organization-wide key can submit an order with or without a Site. Browser events are intent and cannot make a purchase verified.

Confirm once, retry safely

Use a stable external order ID for both the body and Idempotency-Key. The total must equal item subtotal minus discounts plus tax and shipping. A valid cash-on-delivery order can be confirmed before payment.

curl https://api.fendsy.com/v1/orders \
  -H "Authorization: Bearer $FENDSY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{"externalOrderId":"order-1001","customerProfileId":"PROFILE_ID","confirmedAt":"2026-10-14T00:00:00.000Z","currency":"INR","paymentState":"pending","paymentMethod":"cash_on_delivery","items":[{"catalogVariantId":"VARIANT_ID","quantity":1,"unitPrice":"100.00"}],"totalAmount":"100.00"}'

The first accepted request returns 201. Repeating the same body and key returns 200 with duplicate: true. Changing the body for the same external ID returns 409.

Record lifecycle evidence

Use POST /v1/orders/{orderId}/milestones with a unique idempotency key, state, timestamp and merchant reference for each paid, fulfilled, delivered, cancelled or refunded fact. Delivery requires fulfillment; a refund requires payment evidence. A paid order can be cancelled and later refunded.

Fendsy sends no automatic order confirmation from this request. Keep your existing confirmation sender until you explicitly test and switch it. For Shopify checkout, Shopify sends the order confirmation automatically. Shopify says most customer email notifications cannot be deactivated; a Shopify Plus store owner must contact Shopify Support to turn off specific notifications. Fendsy keeps Shopify order confirmation sending unavailable until that change is verified, so customers do not receive duplicate confirmations.