Fulfillments

Mark orders fulfilled and read fulfillment state.

Mark an order fulfilled once the goods have been handed over — built for digital-delivery integrations, so the merchant’s Orders view stops showing every digital sale as perpetually unfulfilled. Fulfillment through the API is all-or-nothing: a fulfillment covers every line item on the transaction (partial, per-item fulfillment stays a dashboard workflow), and no customer notification is sent. Works with a merchant key or an app access token; scoped keys need fulfillments:read / fulfillments:write.

List fulfillments

List the fulfillments on one transaction. fulfillment_status is the order's own roll-up ('unfulfilled' or 'fulfilled'), so you never have to derive it. Requires the fulfillments:read scope on scoped keys.

GEThttps://paysio.com/api/v1/fulfillments

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

transaction_idstring

Required. The transaction to inspect

Example request — cURL

curl -X GET https://paysio.com/api/v1/fulfillments \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/fulfillments", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "object": "fulfillment",
      "id": "8d2e1f0a-4b6c-4d21-9a54-2c3b1e0f9a8d",
      "transaction_id": "6b1e0d3a-9f7c-4d21-8a54-2c3b1e0f9a8d",
      "status": "fulfilled",
      "tracking_number": "1Z999AA10123456784",
      "tracking_carrier": "UPS",
      "tracking_url": null,
      "note": null,
      "items": [
        { "product_id": "uuid", "product_name": "Pro Plan", "quantity": 1 }
      ],
      "created": 1735689600
    }
  ],
  "fulfillment_status": "fulfilled",
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Mark an order fulfilled

Create a fulfillment covering every line item on the transaction and flip the order's fulfillment status. Returns 400 with code 'already_fulfilled' when the order is already fully fulfilled. Requires the fulfillments:write scope on scoped keys.

POSThttps://paysio.com/api/v1/fulfillments

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*) or app access token. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

transaction_idstringrequired

The transaction to fulfill

tracking_numberstring

Optional tracking number (max 200 chars)

tracking_carrierstring

Optional carrier name (max 60 chars)

tracking_urlstring

Optional tracking URL

notestring

Optional note (max 1000 chars)