Asynchronous and manual fulfillment

Payment and delivery are separate in Shoppex. An order can be paid with status: "COMPLETED" while one of its line items is still waiting for delivery. Use asynchronous fulfillment when your system needs more than 15 seconds to generate content. Use manual fulfillment when a merchant needs to prepare an account, link, code, or file after payment. PHYSICAL products have their own lane: the order is marked shipped and then delivered. See Physical products.

Fulfillment is tracked per line item. The invoice payment status does not change when a line item moves between delivery states.

Delivery states

State	Meaning
`PENDING`	The invoice is not paid yet, or automated dynamic delivery is currently in flight.
`AWAITING_FULFILLMENT`	Shoppex expects the vendor or merchant to provide content later.
`DELIVERED`	Delivery content was stored. `delivered_at` contains the delivery time.
`FAILED`	Automated dynamic delivery failed. Merchant action is required.

A line item enters AWAITING_FULFILLMENT in any of these cases:

its dynamic delivery callback returns a clear pending acknowledgement: {"status":"pending"}
it belongs to a DYNAMIC product that has no dynamic_webhook URL configured
it belongs to a PHYSICAL product

The second case is the manual fulfillment lane. After payment, the merchant can deliver the line item from the dashboard or through the Developer API. The third case is the physical lane. There is no separate “shipped” delivery state: a physical line stays AWAITING_FULFILLMENT after the order is marked shipped, and moves to DELIVERED when the order is marked delivered. The shipment itself is reported by the ship endpoint and the order:shipped event.

Read fulfillment state

Order read responses expose these fields on every item. The example below shows the relevant response fields:

{
  "data": {
    "id": "order_db_123",
    "uniqid": "order_123",
    "status": "COMPLETED",
    "items": [
      {
        "id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
        "delivery_status": "AWAITING_FULFILLMENT",
        "delivered_at": null
      }
    ]
  }
}

id is the line item ID used as {item_id} in the fulfillment endpoints. The order path accepts the same order identifier used by the existing order endpoints.

Fulfill a line item

POST /dev/v1/orders/{id}/items/{item_id}/fulfill

The order must be paid with status: "COMPLETED", and the line item must not already be delivered. Provide at least one of message, codes, links, or files. Dynamic delivery callbacks must include delivery_id with the deliveryId from the original webhook request. Shoppex rejects a missing or stale generation, or a recipient that no longer matches that request, with 422. Manual fulfillment without a dynamic delivery event does not require this field.

cURL

curl https://api.shoppex.io/dev/v1/orders/order_123/items/018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f/fulfill \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fulfill-order_123-018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f-v1" \
  -d '{
    "message": "Your account is ready.",
    "codes": ["KEY-1", "KEY-2"],
    "links": [
      {
        "label": "Open your account",
        "url": "https://vendor.example.com/access/abc123"
      }
    ],
    "files": [
      {
        "attachment_id": "018f6f2e-7cb1-7a04-92f9-1cc8d7c8f413"
      }
    ],
    "notify_customer": true
  }'

A successful response returns the delivered line item content:

{
  "data": {
    "line_item_id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
    "delivery_status": "DELIVERED",
    "delivered_at": "2026-08-04T09:15:00.000Z",
    "delivered_items": {
      "delivery_type": "MANUAL",
      "deliveryType": "MANUAL",
      "service_text": "Your account is ready.",
      "serviceText": "Your account is ready.",
      "license_keys": [
        { "key": "KEY-1" },
        { "key": "KEY-2" }
      ],
      "licenseKeys": [
        { "key": "KEY-1" },
        { "key": "KEY-2" }
      ],
      "external_urls": [
        {
          "label": "Open your account",
          "url": "https://vendor.example.com/access/abc123"
        }
      ],
      "externalUrls": [
        {
          "label": "Open your account",
          "url": "https://vendor.example.com/access/abc123"
        }
      ],
      "downloads": [
        {
          "id": "018f6f2e-7cb1-7a04-92f9-1cc8d7c8f413",
          "attachmentId": "018f6f2e-7cb1-7a04-92f9-1cc8d7c8f413",
          "title": "setup-guide.pdf",
          "filename": "setup-guide.pdf",
          "fileName": "setup-guide.pdf",
          "extension": "pdf",
          "size": 184320
        }
      ],
      "count": 5,
      "fulfilled_by": "API",
      "fulfilled_at": "2026-08-04T09:15:00.000Z"
    }
  }
}

Each files[].attachment_id must refer to an existing attachment owned by the same shop. Upload attachments in the dashboard before calling this endpoint. If any attachment is missing or belongs to another shop, the entire request fails and no partial delivery is stored.

Customer email

notify_customer controls the buyer’s “product ready” email:

Omit it, or set it to true, to request the customer email after the content is stored.
Set it to false to store the content without sending that email.

The shop’s normal customer-email settings and notification preferences still apply. Shoppex also sends the order:item.delivered event after a successful fulfillment.

Error responses

Both endpoints reject invalid requests with the standard error envelope. The message distinguishes the cause:

HTTP	Cause	Retryable?
`404 NOT_FOUND`	Order or line item does not exist for this shop (also returned for malformed line-item ids)	No — check the ids from the order response
`422 VALIDATION_ERROR` — “Order is not in a fulfillable state”	The order is not `COMPLETED` yet (unpaid, refunded, voided, or stock-held)	Yes — once the order is paid
`422 VALIDATION_ERROR` — “already has delivered content”	The line item was already delivered (possibly by a concurrent delivery)	No
`422 VALIDATION_ERROR` — content message	Invalid body: empty content, malformed link URL, oversized fields	No — fix the request body and use a new `Idempotency-Key`
`422 VALIDATION_ERROR` — “Attachment … does not exist”	`files[].attachment_id` missing or owned by another shop	No — upload the attachment first
`422 VALIDATION_ERROR` — “Only failed deliveries can be retried”	Retry called on a line item that is not `FAILED`	No
`422 VALIDATION_ERROR` — “Physical items are fulfilled by marking the order shipped and delivered”	Fulfill called on a `PHYSICAL` line item	No — use `/ship` and `/deliver`
`422 VALIDATION_ERROR` — “No failed automated delivery exists”	Retry called where no dynamic-delivery attempt failed	No — fulfill the item manually instead

Idempotency

Both fulfillment endpoints support the standard Idempotency-Key header. Reuse the same key when retrying the same request after a network interruption. Shoppex scopes the key to the authenticated API key and route and replays the stored response during the 24-hour idempotency window. For example, every retry of the delivery above must keep Idempotency-Key: fulfill-order_123-018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f-v1.

Rejected responses (4xx) are replayed too: after correcting a rejected request body — for example a wrong attachment_id — send the corrected request with a new Idempotency-Key. Reusing the old key returns either the stored error or a key-conflict error.

Idempotency does not allow a line item to be delivered twice. Once delivered_at is set, another fulfillment attempt is rejected even if it uses a different key.

Retry failed dynamic delivery

POST /dev/v1/orders/{id}/items/{item_id}/retry-delivery

This endpoint re-queues a failed dynamic delivery and moves the line item from FAILED to PENDING. It does not take a request body.

cURL

curl https://api.shoppex.io/dev/v1/orders/order_123/items/018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f/retry-delivery \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Idempotency-Key: retry-order_123-018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f-v1"

{
  "data": {
    "line_item_id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
    "delivery_status": "PENDING",
    "retried": true
  }
}

Retrying can cause a double delivery. A timeout or network error does not tell you whether the vendor already finished the delivery. If the vendor already delivered the product before Shoppex received the failure, check the vendor system. Make sure it checks X-Shoppex-Idempotency-Key for duplicates before you retry.

Only a FAILED dynamic line item with a failed delivery event can be retried. If no retryable event exists, fulfill the line item manually instead.

Physical products

A PHYSICAL line item is fulfilled by shipping it, not by sending content. The flow:

The buyer enters a shipping address in hosted checkout. Shoppex adds the flat price of the matching shipping zone, once per order.
After payment, every physical line is AWAITING_FULFILLMENT. Digital lines in the same cart deliver as usual.
The merchant or your system marks the order shipped, with an optional tracking code and link. Shoppex sends order:shipped and, by default, a shipping email to the buyer.
The merchant or your system marks the order delivered. Every open physical line moves to DELIVERED, and Shoppex sends order:item.delivered for each of them.

One shipment always covers every physical line of the order. There are no partial shipments.

Mark an order shipped

POST /dev/v1/orders/{id}/ship

Requires the orders.write scope. {id} accepts the order id or uniqid. All body fields are optional.

Field	Type	Description
`tracking_code`	string or null	Carrier tracking code, up to 255 characters. Omit to keep the stored one; `null` clears it.
`tracking_url`	string or null	Tracking link, up to 2048 characters. Must be an `http` or `https` URL. Omit to keep the stored one; `null` clears it.
`notify_customer`	boolean	Send the buyer the shipping email. Defaults to `true`.

cURL

curl https://api.shoppex.io/dev/v1/orders/order_123/ship \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ship-order_123-v1" \
  -d '{
    "tracking_code": "1Z999AA10123456784",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "notify_customer": true
  }'

A successful response returns the shipment:

{
  "data": {
    "shipped_at": "2026-09-23T10:15:00.000Z",
    "delivered_at": null,
    "tracking_code": "1Z999AA10123456784",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }
}

Calling /ship again on a shipped order corrects the tracking. shipped_at keeps the time of the first shipment. A field you leave out keeps its stored value; send null to clear it. The buyer gets one shipping email per distinct tracking. Repeating the call with the same tracking sends no second email; a changed tracking sends an update. The email also follows the shop’s buyer-email settings and the buyer’s notification preferences. Set notify_customer: false to skip it.

Mark an order delivered

POST /dev/v1/orders/{id}/deliver

Requires the orders.write scope. There is no request body.

cURL

curl https://api.shoppex.io/dev/v1/orders/order_123/deliver \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Idempotency-Key: deliver-order_123-v1"

{
  "data": {
    "shipped_at": "2026-09-23T10:15:00.000Z",
    "delivered_at": "2026-09-25T14:02:00.000Z",
    "tracking_code": "1Z999AA10123456784",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }
}

Every physical line that is not delivered yet moves to DELIVERED and gets this delivered-items snapshot:

{
  "delivery_type": "PHYSICAL",
  "deliveryType": "PHYSICAL",
  "count": 1,
  "fulfilled_by": "API",
  "fulfilled_at": "2026-09-25T14:02:00.000Z",
  "tracking_codes": [
    {
      "label": "Tracking",
      "code": "1Z999AA10123456784",
      "url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    }
  ],
  "trackingCodes": [
    {
      "label": "Tracking",
      "code": "1Z999AA10123456784",
      "url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    }
  ]
}

tracking_codes and trackingCodes are present only when the shipment has a tracking code or link. fulfilled_by is API for Developer API calls and MERCHANT for the dashboard. You can deliver an order that was never marked shipped. shipped_at is then set to the delivery time. Delivering sends no email to the buyer.

Which orders can ship

Both endpoints need an order that:

has at least one PHYSICAL line item,
is paid: COMPLETED, or PARTIAL_REFUND where every open physical line is still owed,
has a shipping address.

Because one shipment covers every open physical line, a PARTIAL_REFUND order where one of those lines was refunded cannot ship at all. The request is refused rather than settling a line the order no longer owes.

Error responses

A 409 CONFLICT carries error.subcode with the specific reason, so you can branch on it instead of the message.

HTTP	`error.subcode`	Cause	Retryable?
`404 ORDER_NOT_FOUND`		No order with this `id` or `uniqid` in the shop	No
`422 VALIDATION_ERROR`		`tracking_url` is not an `http`/`https` URL (`details[].field: "tracking"`), or a body field has the wrong type or length	No — fix the body and use a new `Idempotency-Key`
`409 CONFLICT`	`NOTHING_TO_SHIP`	The order has no `PHYSICAL` line	No
`409 CONFLICT`	`ORDER_NOT_FULFILLABLE`	The order is not paid yet, is no longer owed (refunded or voided), a physical line still waits for the buyer’s post-payment details, or a refund or void committed while the request ran	Yes — once the order is paid or the buyer submitted their details; no if it was refunded or voided
`409 CONFLICT`	`ALREADY_DELIVERED`	Every physical line is already `DELIVERED`	No
`409 CONFLICT`	`SHIPPING_ADDRESS_MISSING`	The order has no stored address	No
`403 FORBIDDEN`	The shop is suspended	No

Idempotency

Both endpoints support the standard Idempotency-Key header, scoped to your API key, the route, and the order. A retry with the same key within 24 hours replays the stored response, including a stored error. Without a key, a repeated /ship corrects the tracking (see above) and a repeated /deliver returns 409 CONFLICT with subcode: "ALREADY_DELIVERED". No retry can deliver a line twice.

Orders without an address

A physical order is not payable until the buyer has entered an address in a country one of the shop’s zones covers. Paths that would complete such an order without payment refuse it too: POST /dev/v1/orders/{id}/complete and POST /dev/v1/orders/{id}/fulfill answer 422 VALIDATION_ERROR “This order has physical items but no shipping address yet.”

Physical products can be bought through hosted checkout only. Creating an order that contains one through POST /dev/v1/orders, a dashboard invoice, or POS fails with 400 PHYSICAL_PRODUCT_REQUIRES_CHECKOUT. The reseller program refuses them with RESELLER_PHYSICAL_PRODUCT_UNSUPPORTED: physical products cannot be enrolled in the reseller catalog or ordered wholesale.

Buyer-facing shipping state

The public invoice that hosted checkout reads carries a shipping object on physical orders. Because anyone with the checkout link can read it, it holds no name, street, or phone, only address_summary with city and country:

{
  "shipping": {
    "required": true,
    "address_summary": { "city": "Berlin", "country": "DE" },
    "countries": ["AT", "CH", "DE"],
    "zone_name": "Europe",
    "free_shipping_applied": false,
    "shipped_at": "2026-09-23T10:15:00.000Z",
    "delivered_at": null,
    "tracking_code": "1Z999AA10123456784",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }
}

address_summary is null until the buyer saves an address. countries lists every country the shop ships to. The full address is shown only in the dashboard and, to the signed-in buyer, in the customer portal. The buyer-facing errors while saving the address or paying are:

Code	HTTP	Meaning
`SHOP_DOES_NOT_SHIP`	400	The cart has a physical product and the shop has no shipping zone. The order is not created.
`SHIPPING_COUNTRY_NOT_SERVED`	400	No zone covers the address country. `params.country` names it.
`SHIPPING_ADDRESS_REQUIRED`	409	A payment was started before an address was saved.

Shipping zones

A shipping zone is a flat shipping price for a list of countries. Manage zones with the products.read and products.write scopes.

Endpoint	Purpose
`GET /dev/v1/shipping-zones`	List every zone. A shop has at most 100, so the list is not paginated.
`GET /dev/v1/shipping-zones/{id}`	Get one zone.
`POST /dev/v1/shipping-zones`	Create a zone. Returns `201`.
`PUT /dev/v1/shipping-zones/{id}`	Replace a zone, including its full country list.
`DELETE /dev/v1/shipping-zones/{id}`	Delete a zone. Returns `204` with no body.

POST and PUT take the same body:

Field	Type	Description
`name`	string	1 to 120 characters.
`currency`	string	ISO 4217 code of a supported fiat currency. The price and threshold are in this currency.
`price`	number	Flat price per order, `0` to `99999999`. Stored with 2 decimals.
`free_shipping_threshold`	number or null	Optional. Order value from which shipping is free, compared with the goods after discounts, in the zone currency. `null` or omitted disables it.
`countries`	string[]	1 to 300 ISO 3166-1 alpha-2 codes. Case and duplicates do not matter.

cURL

curl https://api.shoppex.io/dev/v1/shipping-zones \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zone-europe-v1" \
  -d '{
    "name": "Europe",
    "currency": "EUR",
    "price": 4.9,
    "free_shipping_threshold": 50,
    "countries": ["DE", "AT", "FR"]
  }'

{
  "data": {
    "id": "019d7a2e-1c3b-7f10-9a44-2b1c3d4e5f60",
    "name": "Europe",
    "currency": "EUR",
    "price": 4.9,
    "free_shipping_threshold": 50,
    "countries": ["AT", "DE", "FR"],
    "created_at": 1790158500,
    "updated_at": 1790158500
  }
}

countries comes back upper-case and sorted. created_at and updated_at are Unix timestamps. The list endpoint returns the same objects in data, oldest first, with pagination.has_more: false. A country can belong to only one zone per shop. Write errors: Every refusal but the 404 carries error.subcode.

HTTP	`error.subcode`	Cause
`409 CONFLICT`	`SHIPPING_ZONE_COUNTRY_CONFLICT`	A country is already in another zone. `details` has one entry per taken country, naming the zone and its id.
`422 VALIDATION_ERROR` (`details[].field`: `name`, `currency`, `price`, `free_shipping_threshold`, or `countries`)	`SHIPPING_ZONE_INVALID_NAME`, `SHIPPING_ZONE_INVALID_CURRENCY`, `SHIPPING_ZONE_INVALID_AMOUNT`, `SHIPPING_ZONE_NO_COUNTRIES`, `SHIPPING_ZONE_INVALID_COUNTRIES`	Invalid field: empty name, unsupported currency, negative amount, no countries, or an unknown country code
`422 VALIDATION_ERROR` (`details[].field: "shipping_zone"`)	`SHIPPING_ZONE_LIMIT_REACHED`	The shop already has 100 zones
`404 SHIPPING_ZONE_NOT_FOUND`	No zone with this `id` in the shop

All write endpoints support Idempotency-Key. Changing or deleting a zone does not change orders that are already paid. An unpaid order is quoted again with the current zone the next time the buyer changes the address, coupon, tip, or payment method; if no zone covers its country any more, that step fails with SHIPPING_COUNTRY_NOT_SERVED.

Fulfillment webhook events

These are normal merchant webhook events. Subscribe to them in Settings → Webhooks or through the Developer API. They use the normal event-webhook signature, not the product’s dynamic delivery signing secret.

`order:item.delivered`

Sent after late content is stored through manual or API fulfillment, and once per physical line when an order is marked delivered.

{
  "event": "order:item.delivered",
  "data": {
    "invoiceId": "order_123",
    "lineItemId": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
    "productId": "product_db_123",
    "fulfilledBy": "API",
    "deliveryStatus": "DELIVERED",
    "deliveredAt": "2026-08-04T09:15:00.000Z",
    "licenseKeys": [
      { "key": "KEY-1" }
    ],
    "deliveredItems": {
      "delivery_type": "MANUAL",
      "deliveryType": "MANUAL",
      "license_keys": [{ "key": "KEY-1" }],
      "licenseKeys": [{ "key": "KEY-1" }],
      "count": 1,
      "fulfilled_by": "API",
      "fulfilled_at": "2026-08-04T09:15:00.000Z"
    }
  },
  "created_at": 1785834900
}

deliveredItems is the committed delivery snapshot returned by the fulfillment request. licenseKeys is included as a convenience when the snapshot contains codes, so consumers do not need to fetch the order after receiving the event. Both fields can contain sensitive buyer delivery content and should not be logged. For a physical line, deliveredItems is the physical snapshot with delivery_type: "PHYSICAL" and the tracking, and there is no licenseKeys field.

`order:shipped`

Sent when an order’s physical items are marked shipped, from the dashboard or through POST /dev/v1/orders/{id}/ship. A tracking correction on an already shipped order sends it again with firstShipment: false.

{
  "event": "order:shipped",
  "data": {
    "invoiceId": "order_123",
    "shippedBy": "API",
    "firstShipment": true,
    "shippedAt": "2026-09-23T10:15:00.000Z",
    "trackingCode": "1Z999AA10123456784",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "lineItemIds": [
      "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f"
    ]
  },
  "created_at": 1790158500
}

Field	Description
`invoiceId`	The order `uniqid`.
`shippedBy`	`MERCHANT` (dashboard) or `API` (Developer API).
`firstShipment`	`true` for the first shipment, `false` for a tracking correction.
`shippedAt`	Time of the first shipment. It does not change on a correction.
`trackingCode`, `trackingUrl`	The current tracking, or `null`.
`lineItemIds`	The physical line items the shipment covers: every physical line not delivered yet.

The payload does not contain the shipping address.

`order:item.delivery_failed`

Sent when the single dynamic delivery attempt ends in a terminal failure. Shoppex also marks the line item FAILED and notifies the merchant.

{
  "event": "order:item.delivery_failed",
  "data": {
    "invoiceId": "order_123",
    "lineItemId": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
    "productId": "product_db_123",
    "error": "Dynamic delivery request timed out after 15000ms"
  },
  "created_at": 1785834000
}

These events report fulfillment state. They do not change or replace payment events such as order:paid. They go to shop-level webhook subscriptions only; a webhook configured on a single product does not receive them.

Dynamic product delivery

Implement the synchronous and asynchronous callback contract.

Webhook events

Verify normal merchant webhook signatures and review event payloads.

Start here

Agents & CLI

Products

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Elements

Integrations

Customers

Resellers

Email marketing

Tutorials

Asynchronous and manual fulfillment

Delivery states

Read fulfillment state

Fulfill a line item

Customer email

Error responses

Idempotency

Retry failed dynamic delivery

Physical products

Mark an order shipped

Mark an order delivered

Which orders can ship

Error responses

Idempotency

Orders without an address

Buyer-facing shipping state

Shipping zones

Fulfillment webhook events

`order:item.delivered`

`order:shipped`

`order:item.delivery_failed`

Dynamic product delivery

Webhook events

​Delivery states

​Read fulfillment state

​Fulfill a line item

​Customer email

​Error responses

​Idempotency

​Retry failed dynamic delivery

​Physical products

​Mark an order shipped

​Mark an order delivered

​Which orders can ship

​Error responses

​Idempotency

​Orders without an address

​Buyer-facing shipping state

​Shipping zones

​Fulfillment webhook events

​order:item.delivered

​order:shipped

​order:item.delivery_failed

Dynamic product delivery

Webhook events

Delivery states

Read fulfillment state

Fulfill a line item

Customer email

Error responses

Idempotency

Retry failed dynamic delivery

Physical products

Mark an order shipped

Mark an order delivered

Which orders can ship

Error responses

Idempotency

Orders without an address

Buyer-facing shipping state

Shipping zones

Fulfillment webhook events

`order:item.delivered`

`order:shipped`

`order:item.delivery_failed`