Orders

Submit order data to ChargebackStop for chargeback prevention and dispute resolution. This API powers integrations with Mastercard Consumer Clarity, Visa Order Insight, and chargeback alert matching.

Base URL: https://api.chargebackstop.com/v1/orders/

Authentication: Bearer token via API key. Required abilities vary by endpoint (all newly created API keys include these Orders abilities by default):

orders:read for GET endpoints
orders:write for POST endpoints
orders:update for PATCH endpoints

Rate limits:

100 requests per minute per endpoint, per organisation/partner group
Each endpoint has an independent rate limit pool (e.g., hitting the list limit doesn't affect create)
Rate limits are applied by owner (organisation or partner group), not by API key
Exceeding the limit returns 429 Too Many Requests

Batch Limit: Maximum 100 orders per request (POST only).

GET /v1/orders - List Orders

Retrieve a paginated list of orders with optional filtering and sorting.

Authentication: Bearer token via API key with orders:read ability.

Query parameters

Parameter	Type	Description
`organisation_id`	string	Filter by organisation ID
`integration_id`	string	Filter by integration ID
`reference_id`	string	Filter by exact reference_id
`type`	string	Filter by order type: `COMPLETE` or `PARTIAL`
`order_status`	string	Filter by status: `OPEN_PENDING`, `OPEN_PENDING_RETURN`, `CLOSED_COMPLETE`, `CLOSED_CANCELLED`, `OTHER`
`created_at_gte`	datetime	Orders created on or after this timestamp (ISO 8601)
`created_at_lte`	datetime	Orders created on or before this timestamp (ISO 8601)
`sort`	string	Sort field: `created_at` (oldest first), `-created_at` (newest first, default), `order_datetime`, `-order_datetime`
`limit`	integer	Number of results per page (default: 100)
`offset`	integer	Number of results to skip for pagination

Example request

curl -X GET "https://api.chargebackstop.com/v1/orders/?reference_id=order-2024-001&sort=-created_at&limit=10" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "items": [
    {
      "id": "ord_abc123",
      "reference_id": "order-2024-001",
      "type": "COMPLETE",
      "organisation_id": "org_xyz",
      "integration_id": "int_123",
      "created_at": "2024-01-15T10:30:00Z",
      "order_datetime": "2024-01-15T10:30:00Z",
      "order_number": "ORD-2024-001",
      "order_status": "CLOSED_COMPLETE",
      "order_currency": "USD",
      "order_total_amount_in_cents": 9720,
      "transactions": [...],
      "deliveries": [...],
      "items": [...],
      "refunds": [...],
      "subscriptions": [...],
      "disputes": [...],
      "links": [
        {
          "rel": "self",
          "uri": "/v1/orders/ord_abc123"
        }
      ]
    }
  ],
  "count": 1
}

GET /v1/orders/{order_id} - Get Order by ID

Retrieve a single order by its internal id (the id field returned in JSON responses), not by reference_id.

To retrieve an order by reference_id, use the list endpoint: GET /v1/orders?reference_id=<your_reference_id>.

Authentication: Bearer token via API key with orders:read ability.

URL parameters

Parameter	Type	Description
`order_id`	string	The internal order ID (e.g., `ord_abc123`)

Example request

curl -X GET "https://api.chargebackstop.com/v1/orders/ord_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

Returns the full order object with all nested relations (transactions, deliveries, items, refunds, subscriptions, disputes).

{
  "id": "ord_abc123",
  "reference_id": "order-2024-001",
  "type": "COMPLETE",
  "organisation_id": "org_xyz",
  "integration_id": "int_123",
  "created_at": "2024-01-15T10:30:00Z",
  "order_datetime": "2024-01-15T10:30:00Z",
  "order_number": "ORD-2024-001",
  "order_status": "CLOSED_COMPLETE",
  "order_currency": "USD",
  "order_total_amount_in_cents": 9720,
  "customer_email": "john.doe@example.com",
  "transactions": [...],
  "deliveries": [...],
  "items": [...],
  "refunds": [...],
  "subscriptions": [...],
  "disputes": [...],
  "links": [
    {
      "rel": "self",
      "uri": "/v1/orders/ord_abc123"
    }
  ]
}

Error responses

404 Not Found - Order does not exist or is not accessible:

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Not found"
    }
  ]
}

POST /v1/orders - Create Orders

Submit order data to ChargebackStop for chargeback prevention and dispute resolution.

Authentication: Bearer token via API key with orders:write ability.

Rate Limit: 100 requests per minute per organisation/partner group.

Batch Limit: Maximum 100 orders per request.

Request Body: JSON array of order objects (even when submitting a single order).

Schema validation before partial success: Partial success applies after request schema validation. If the top-level request is invalid (for example, body is not an array or fields have invalid types), the API returns a full-request 422 and no orders are processed.

Status codes: 200 means the batch was processed, not that every order was created — check the errors array. A batch where every order fails returns 400 with the same response shape. See Response format.

Which mode should I use?

Mode	Use Case	Integration Type
PARTIAL	You have an existing payment processor integration (Stripe, Adyen, etc.) and want to submit enrichment data linked to those processor transactions	Any non-CUSTOM_ORDERS integration
COMPLETE	You do not have an existing payment processor integration to enrich and want to submit full order data directly (for digital receipts, deflection, or alert matching)	CUSTOM_ORDERS integration only

Important: Order type and integration type must match

COMPLETE orders can ONLY be created with CUSTOM_ORDERS integrations. Attempting to create a COMPLETE order on a Stripe, Adyen, or other payment processor integration will return INVALID_ORDER_TYPE.

PARTIAL orders can ONLY be created with non-CUSTOM_ORDERS integrations (Stripe, Adyen, Shopify, etc.) and require orders enrichment to be enabled by ChargebackStop support. Attempting to create a PARTIAL order on a CUSTOM_ORDERS integration will return INVALID_ORDER_TYPE.

PARTIAL mode - enrichment for existing integrations

Use PARTIAL mode when you already have a payment processor integration (Stripe, Adyen, Shopify, etc.) connected to ChargebackStop and want to enrich your orders with additional data.

Getting started

Prerequisites:

An existing integration (Stripe, Adyen, etc.) with orders enrichment enabled by the ChargebackStop team
API key with orders:write ability

Minimal required fields:

Field	Description
`type`	Must be `"PARTIAL"`
`organisation_id`	Your organisation ID
`integration_id`	Your integration ID
`reference_id`	Unique order identifier
`order_email`	Email associated with the order
`customer_account_id`	Customer identifier (email, username, or account ID)

Device identifier required: PARTIAL orders must include at least one of: device_ip_address, device_id, or device_fingerprint. This is used for fraud prevention and dispute evidence.

Example 1: Basic PARTIAL Order

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",
    "order_email": "customer@example.com",
    "customer_account_id": "customer@example.com",
    "device_ip_address": "216.24.60.17"
  }
]

Digital receipts and deflection field sets

These field sets are required for PARTIAL mode, and are required for all order modes when digital receipts or deflection is enabled.

Examples below use PARTIAL payloads, but the same field sets can be included in COMPLETE orders.

Mastercard Consumer Clarity

Consumer Clarity helps reduce chargebacks by providing cardholders with detailed purchase information in their banking app, making transactions more recognisable.

Required fields for Consumer Clarity:

Field	Description
`order_datetime`	When the order was placed (ISO 8601)
`order_number`	Customer-facing order number
`order_subtotal_amount_in_cents`	Subtotal before tax
`order_currency`	Currency code (ISO 4217)
`order_total_amount_in_cents`	Total amount including tax

Example 2: Consumer Clarity (Mastercard)

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",
    "order_email": "customer@example.com",
    "customer_account_id": "cust-12345",
    "device_ip_address": "216.24.60.83",

    "order_datetime": "2024-01-15T10:30:00Z",
    "order_number": "ORD-2024-001",
    "order_subtotal_amount_in_cents": 4500,
    "order_currency": "USD",
    "order_total_amount_in_cents": 4950
  }
]

Visa Order Insight

Order Insight provides Visa cardholders with purchase details directly in their banking app, helping them recognise legitimate transactions.

Required fields for Order Insight:

Field	Description
`items`	Array with at least one item containing `name`

Example 3: Order Insight (Visa)

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",
    "order_email": "customer@example.com",
    "customer_account_id": "cust-12345",
    "device_ip_address": "216.24.60.142",

    "items": [
      {
        "reference_id": "item-001",
        "name": "Widget Pro",
        "price_in_cents": 4500,
        "quantity": 1
      }
    ]
  }
]

Product and merchant information

Some merchants (particularly Merchant of Record platforms) may need to include product and merchant information with each order if default settings are not configured in the platform.

Note: If product and merchant information varies per order, include it in each order submission. If the values are stable across all orders, you can set defaults in the ChargebackStop platform instead.

Product information fields:

Field	Description
`items[].name`	Product name
`items[].price_in_cents`	Item price
`items[].quantity`	Quantity ordered

Merchant information fields:

Field	Description
`merchant_name`	Corporate/parent company name
`merchant_contact_phone`	Customer service phone (E.164 format)
`merchant_store_name`	Store name recognisable to customer
`merchant_url`	Merchant website URL

Example 4: Product and merchant information

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",
    "order_email": "customer@example.com",
    "customer_account_id": "cust-12345",
    "device_ip_address": "216.24.60.201",

    "merchant_name": "Example Corporation",
    "merchant_contact_phone": "+14155551234",
    "merchant_store_name": "Example Store",
    "merchant_url": "https://example.com",

    "items": [
      {
        "reference_id": "item-001",
        "name": "Widget Pro",
        "price_in_cents": 4500,
        "quantity": 1
      }
    ]
  }
]

First-Party Trust (FPT) - Mastercard

First-Party Trust is a Mastercard programme that helps identify legitimate transactions by linking customer identity data (email, device) across purchases. This strengthens fraud prevention and reduces first-party fraud chargebacks.

Required fields for FPT:

Field	Description
`customer_email`	Customer's email address
`order_email`	Email associated with the order
Device identifier	At least one of: `device_ip_address`, `device_id`, or `device_fingerprint`

Example 5: First-Party Trust (Mastercard)

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",

    "customer_email": "john.doe@example.com",
    "order_email": "john.doe@example.com",
    "customer_account_id": "cust-12345",

    "device_ip_address": "216.24.60.58",
    "device_id": "device-abc123",
    "device_fingerprint": "fp-xyz789"
  }
]

Compelling Evidence 3.0 (CE3.0) - Visa

Compelling Evidence 3.0 is a Visa programme that helps merchants win disputes by proving the cardholder has a history of legitimate purchases. By submitting customer and device data with each order, you build evidence that can be used in dispute responses.

Required fields for CE3.0:

Field	Description
`customer_email`	Customer's email address
Device identifier	At least one of: `device_ip_address`, `device_id`, or `device_fingerprint`

Example 6: Compelling Evidence 3.0 (Visa)

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "order-2024-001",

    "customer_email": "john.doe@example.com",
    "order_email": "john.doe@example.com",
    "customer_account_id": "cust-12345",

    "device_ip_address": "216.24.60.229",
    "device_fingerprint": "fp-xyz789"
  }
]

COMPLETE mode

Use COMPLETE mode when you do not have an existing payment processor integration to enrich and want to submit full order data directly to ChargebackStop. This mode supports digital receipts, deflection, and alert matching, and is for merchants using the CUSTOM_ORDERS integration type.

Getting started

Prerequisites:

A CUSTOM_ORDERS integration
API key with orders:write ability

Required fields for COMPLETE orders:

Field	Description
`type`	Must be `"COMPLETE"`
`organisation_id`	Your organisation ID
`integration_id`	Your CUSTOM_ORDERS integration ID
`reference_id`	Unique order identifier
`order_datetime`	When the order was placed
`order_number`	Customer-facing order number
`order_subtotal_amount_in_cents`	Subtotal before tax
`order_currency`	Currency code (ISO 4217)
`order_total_amount_in_cents`	Total amount
`order_status`	Order status

Alert matching

To match orders with chargeback alerts, you must include at least one transaction with specific fields that enable accurate matching. The richer the data set you provide, the better the matching accuracy will be — we recommend including as many transaction fields as possible.

Required transaction fields:

Field	Description
`amount_in_cents`	Transaction amount
`currency`	Currency code
`authorised_at`	When authorisation occurred
`payment_method_type`	Payment method (e.g., `CARD`)
`authorisation_status`	Status (e.g., `SETTLED`)

Additional required fields for card payments:

Field	Description
`payment_method_card_last_4`	Last 4 digits of card
`payment_method_card_brand`	Card brand (e.g., `VISA`)

Matching identifiers (send all three whenever possible):

Identifier	Recommendation	Notes
`acquirer_reference_number`	Send whenever available	Most reliable; directly links to the network transaction
`authorisation_code`	Send whenever available	Improves matching when paired with card details (especially `payment_method_card_last_4`)
`payment_method_card_bin`	Send whenever available	Improves matching when combined with card details and amount/currency

For card payments, at least one matching identifier is required. Best practice is to send all three identifiers whenever available, or as many as possible.

Why these fields matter:

ARN (Acquirer Reference Number): The most reliable identifier for matching - directly links to the network transaction
Authorisation Code: The 6-digit code from the issuer, used with card last 4 when ARN is not available
Card BIN: The first 6-8 digits of the card, helps narrow down matches when combined with other card details and amount

Note: It is worth sending any related refunds and disputes for the order. Including these records helps us detect invalid alerts more accurately.

Example 7: Alert matching (COMPLETE)

[
  {
    "type": "COMPLETE",
    "organisation_id": "org_abc123",
    "integration_id": "int_custom789",
    "reference_id": "order-2024-001",

    "order_datetime": "2024-01-15T10:30:00Z",
    "order_number": "ORD-2024-001",
    "order_subtotal_amount_in_cents": 9000,
    "order_currency": "USD",
    "order_tax_amount_in_cents": 720,
    "order_total_amount_in_cents": 9720,
    "order_status": "CLOSED_COMPLETE",

    "customer_email": "john.doe@example.com",
    "customer_first_name": "John",
    "customer_last_name": "Doe",

    "transactions": [
      {
        "reference_id": "txn-001",
        "amount_in_cents": 9720,
        "currency": "USD",
        "payment_method_type": "CARD",
        "authorisation_status": "SETTLED",
        "payment_method_reference_id": "pm_card_abc123",
        "authorised_at": "2024-01-15T10:30:05Z",
        "descriptor": "EXAMPLE STORE",
        "descriptor_prefix": "EXAMPLE",
        "descriptor_suffix": "STORE",
        "settlement_datetime": "2024-01-16T00:00:00Z",
        "cvc_verified": true,
        "three_d_secure_verified": true,

        "acquirer_reference_number": "74027012345678901234567",
        "authorisation_code": "123456",
        "network_id": "network-txn-123",

        "payment_method_card_brand": "VISA",
        "payment_method_card_last_4": "4242",
        "payment_method_card_bin": "424242",
        "payment_method_card_exp_month": 12,
        "payment_method_card_exp_year": 2026,
        "payment_method_card_wallet_type": "APPLE_PAY",
        "payment_method_card_issuer": "Chase Bank",
        "billing_address": {
          "line_1": "123 Main St",
          "line_2": "Apt 4B",
          "city": "New York",
          "country_subdivision": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      }
    ],

    "refunds": [
      {
        "reference_id": "refund-001",
        "amount_in_cents": 4500,
        "currency": "USD",
        "status": "SUCCEEDED",
        "original_transaction_reference_id": "txn-001",
        "refund_datetime": "2024-01-17T12:00:00Z"
      }
    ],

    "disputes": [
      {
        "reference_id": "dispute-001",
        "amount_in_cents": 4500,
        "currency": "USD",
        "stage": "1ST_CHARGEBACK",
        "status": "OPEN",
        "type": "CHARGEBACK",
        "network_reason_code": "10.4",
        "is_rapid_dispute_resolution": false,
        "evidence_due_by": "2024-02-15T23:59:59Z",
        "payment_method_type": "CARD",
        "card_brand": "VISA"
      }
    ]
  }
]

Example 8: Full COMPLETE Order

This example includes all available fields for a COMPLETE order.

[
  {
    "type": "COMPLETE",
    "organisation_id": "org_abc123",
    "integration_id": "int_custom789",
    "reference_id": "order-2024-001",

    "order_datetime": "2024-01-15T10:30:00Z",
    "order_number": "ORD-2024-001",
    "order_subtotal_amount_in_cents": 9000,
    "order_currency": "USD",
    "order_tax_amount_in_cents": 720,
    "order_total_amount_in_cents": 9720,
    "order_status": "CLOSED_COMPLETE",
    "order_phone": "+14155551234",
    "order_is_adult_content": false,

    "order_request_refund_url": "https://example.com/orders/ORD-2024-001/refund",
    "order_buy_again_url": "https://example.com/orders/ORD-2024-001/reorder",
    "order_write_review_url": "https://example.com/orders/ORD-2024-001/review",
    "order_view_url": "https://example.com/orders/ORD-2024-001",

    "order_proof_of_consent": "Customer agreed to Terms of Service on 2024-01-15 via checkout checkbox",
    "order_communications": "Order confirmation email sent 2024-01-15. Shipping notification sent 2024-01-16.",

    "customer_email": "john.doe@example.com",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_account_id": "john.doe@example.com",
    "order_email": "john.doe@example.com",

    "device_ip_address": "216.24.60.94",
    "device_id": "device-abc123",
    "device_fingerprint": "fp-xyz789",

    "merchant_reference_id": "merchant-001",
    "merchant_name": "Example Corporation",
    "merchant_store_name": "Example Store",
    "merchant_store_description": "Your one-stop shop for widgets and gadgets",
    "merchant_contact_email": "receipts@example.com",
    "merchant_customer_service_email": "support@example.com",
    "merchant_contact_phone": "+14155559876",
    "merchant_address": {
      "line_1": "100 Commerce St",
      "line_2": "Suite 500",
      "line_3": "Building A",
      "city": "San Francisco",
      "country_subdivision": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "merchant_store_url": "https://store.example.com",
    "merchant_url": "https://example.com",
    "merchant_terms_and_conditions_url": "https://example.com/terms",
    "merchant_logo_url": "https://example.com/logo.png",
    "merchant_refund_policy_url": "https://example.com/refund-policy",

    "transactions": [
      {
        "reference_id": "txn-001",
        "amount_in_cents": 9720,
        "currency": "USD",
        "payment_method_type": "CARD",
        "authorisation_status": "SETTLED",
        "payment_method_reference_id": "pm_card_abc123",
        "authorised_at": "2024-01-15T10:30:05Z",
        "descriptor": "EXAMPLE STORE",
        "descriptor_prefix": "EXAMPLE",
        "descriptor_suffix": "STORE",
        "authorisation_code": "123456",
        "acquirer_reference_number": "74027012345678901234567",
        "retrieval_reference_number": "401512345678",
        "network_id": "network-txn-123",
        "settlement_datetime": "2024-01-16T00:00:00Z",
        "cvc_verified": true,
        "three_d_secure_verified": true,
        "payment_method_card_brand": "VISA",
        "payment_method_card_last_4": "4242",
        "payment_method_card_exp_month": 12,
        "payment_method_card_exp_year": 2026,
        "payment_method_card_bin": "424242",
        "payment_method_card_wallet_type": "APPLE_PAY",
        "payment_method_card_issuer": "Chase Bank",
        "payment_method_cardholder_name": "John Doe",
        "billing_address": {
          "line_1": "123 Main St",
          "line_2": "Apt 4B",
          "city": "New York",
          "country_subdivision": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      }
    ],

    "deliveries": [
      {
        "reference_id": "dlv-physical-001",
        "type": "PHYSICAL",
        "physical_shipping_carrier": "UPS",
        "physical_shipping_tracking_number": "1Z999AA10123456784",
        "physical_shipping_status": "DELIVERED",
        "physical_shipping_datetime_shipped": "2024-01-16T08:00:00Z",
        "physical_shipping_datetime_delivered": "2024-01-18T14:30:00Z",
        "physical_shipping_address": {
          "line_1": "123 Main St",
          "line_2": "Apt 4B",
          "city": "New York",
          "country_subdivision": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      },
      {
        "reference_id": "dlv-digital-001",
        "type": "DIGITAL",
        "digital_delivery_datetime": "2024-01-15T10:35:00Z",
        "digital_download_start_datetime": "2024-01-15T10:36:00Z",
        "digital_download_end_datetime": "2024-01-15T10:37:00Z",
        "digital_delivery_ip_address": "216.24.60.175",
        "digital_notification_sent": true,
        "digital_notification_sent_datetime": "2024-01-15T10:35:00Z",
        "digital_notification_method": "EMAIL"
      }
    ],

    "items": [
      {
        "reference_id": "item-001",
        "name": "Widget Pro",
        "price_in_cents": 4500,
        "quantity": 2,
        "product_url": "https://example.com/products/widget-pro",
        "product_reference_id": "prod-widget-pro",
        "sku": "WIDGET-PRO-001",
        "delivery_reference_id": "dlv-physical-001"
      },
      {
        "reference_id": "item-002",
        "name": "Digital License Key",
        "price_in_cents": 0,
        "quantity": 1,
        "product_url": "https://example.com/products/license",
        "product_reference_id": "prod-license",
        "sku": "LICENSE-001",
        "delivery_reference_id": "dlv-digital-001",
        "subscription_reference_id": "sub-001"
      }
    ],

    "refunds": [
      {
        "reference_id": "refund-001",
        "amount_in_cents": 4500,
        "currency": "USD",
        "status": "SUCCEEDED",
        "original_transaction_reference_id": "txn-001",
        "refund_datetime": "2024-01-17T12:00:00Z",
        "retrieval_reference_number": "401512345679",
        "reason": "REQUESTED_BY_CUSTOMER"
      }
    ],

    "subscriptions": [
      {
        "reference_id": "sub-001",
        "interval": "MONTH",
        "interval_price_in_cents": 2999,
        "interval_currency": "USD",
        "status": "ACTIVE",
        "display_name": "Pro Plan Monthly",
        "trial_start_date": "2024-01-01T00:00:00Z",
        "trial_end_date": "2024-01-14T23:59:59Z",
        "trial_price_in_cents": 0,
        "trial_currency": "USD",
        "start_date": "2024-01-15T00:00:00Z",
        "next_charge_date": "2024-02-15T00:00:00Z"
      }
    ],

    "disputes": [
      {
        "reference_id": "dispute-001",
        "amount_in_cents": 4500,
        "currency": "USD",
        "stage": "1ST_CHARGEBACK",
        "status": "OPEN",
        "type": "CHARGEBACK",
        "network_reason_code": "10.4",
        "is_rapid_dispute_resolution": false,
        "evidence_due_by": "2024-02-15T23:59:59Z",
        "payment_method_type": "CARD",
        "card_brand": "VISA"
      }
    ]
  }
]

API reference

Required column abbreviations:

Abbreviation	Feature
CC	Consumer Clarity (Mastercard)
FPT	First Party Trust (Mastercard)
OI	Order Insight (Visa)
CE3.0	Compelling Evidence 3.0 (Visa)

Validation wording note:

Required means the field must be present in the request payload. It does not, by itself, imply a non-empty string value.
1-255 chars means the API enforces a non-empty string.
Up to 255 chars means the API enforces only a maximum length, and an empty string may still be accepted when the field is otherwise optional.

Order fields

Core fields

Field	Type	Required	Validation	Description
`type`	string	Yes	`COMPLETE` or `PARTIAL`	Order type discriminator
`organisation_id`	string	Yes	Valid org ID	Your organisation ID
`integration_id`	string	Yes	Valid integration ID	Integration ID
`reference_id`	string	Yes	1-255 chars	Unique order identifier

Order details

Field	Type	Required	Validation	Description
`order_datetime`	datetime	`COMPLETE` orders, and for CC when enabled	ISO 8601	When the order was placed
`order_number`	string	`COMPLETE` orders, and for CC when enabled	Up to 255 chars	Customer-facing order number
`order_subtotal_amount_in_cents`	integer	`COMPLETE` orders, and for CC when enabled	>= 0	Subtotal before tax
`order_currency`	string	`COMPLETE` orders, and for CC when enabled	ISO 4217	Currency code
`order_tax_amount_in_cents`	integer	No	>= 0	Tax amount
`order_total_amount_in_cents`	integer	`COMPLETE` orders, and for CC when enabled	>= 0	Total amount
`order_status`	enum	`COMPLETE` orders	`OPEN_PENDING`, `OPEN_PENDING_RETURN`, `CLOSED_COMPLETE`, `CLOSED_CANCELLED`, `OTHER`	Order status
`order_status_other_description`	string	If `order_status` is `OTHER`	1-255 chars	Description when status is OTHER
`order_phone`	string	No	E.164 format	Order contact phone
`order_is_adult_content`	boolean	No	-	Adult content flag

Order URLs

Field	Type	Required	Validation	Description
`order_request_refund_url`	string	No	Valid URL, up to 255 chars	Refund request URL
`order_buy_again_url`	string	No	Valid URL, up to 255 chars	Reorder URL
`order_write_review_url`	string	No	Valid URL, up to 255 chars	Review URL
`order_view_url`	string	No	Valid URL, up to 255 chars	Order view URL

Order evidence

Field	Type	Required	Validation	Description
`order_proof_of_consent`	string	No	Up to 500 chars	Proof of customer consent
`order_communications`	string	No	Up to 1000 chars	Communications history

Customer fields

Field	Type	Required	Validation	Description
`customer_email`	string	For FPT, CE3.0	Valid email	Customer's email
`customer_first_name`	string	No	Up to 255 chars	First name
`customer_last_name`	string	No	Up to 255 chars	Last name
`customer_account_id`	string	`PARTIAL` orders	Up to 255 chars	Customer identifier
`order_email`	string	`PARTIAL` orders, and for FPT when enabled	Valid email	Order email

Device fields

Field	Type	Required	Validation	Description
`device_ip_address`	string	`PARTIAL` orders, and for FPT/CE3.0 when enabled (at least one)	IPv4/IPv6	Customer's IP
`device_id`	string	`PARTIAL` orders, and for FPT/CE3.0 when enabled (at least one)	Up to 255 chars	Device ID
`device_fingerprint`	string	`PARTIAL` orders, and for FPT/CE3.0 when enabled (at least one)	Up to 255 chars	Device fingerprint

At least one device identifier is required for PARTIAL orders, and for FPT/CE3.0 when enabled.

Merchant fields

Field	Type	Required	Validation	Description
`merchant_reference_id`	string	No	Up to 255 chars	Internal merchant reference
`merchant_name`	string	When default merchant not configured	Up to 255 chars	Corporate name
`merchant_store_name`	string	When default merchant not configured	Up to 255 chars	Store name
`merchant_store_description`	string	No	Up to 255 chars	Store description
`merchant_contact_email`	string	No	Valid email	Receipt email
`merchant_customer_service_email`	string	No	Valid email	Support email
`merchant_contact_phone`	string	When default merchant not configured	E.164	Support phone
`merchant_url`	string	When default merchant not configured	URL	Merchant URL
`merchant_store_url`	string	No	URL	Store URL
`merchant_terms_and_conditions_url`	string	No	URL	T&C URL
`merchant_logo_url`	string	No	URL	Logo URL
`merchant_refund_policy_url`	string	No	URL	Refund policy URL

Merchant address

Field	Type	Required	Description
`merchant_address.line_1`	string	At least one line required when `merchant_address` is provided	Address line 1
`merchant_address.line_2`	string	At least one line required when `merchant_address` is provided	Address line 2
`merchant_address.line_3`	string	At least one line required when `merchant_address` is provided	Address line 3
`merchant_address.city`	string	Required when `merchant_address` is provided	City
`merchant_address.country_subdivision`	string	Required when `merchant_address` is provided	State/province
`merchant_address.postal_code`	string	Required when `merchant_address` is provided	Postal code
`merchant_address.country`	string	Required when `merchant_address` is provided	Country code

Request/response shape: Both requests and responses use nested merchant_address.

Transactions

Limit: Maximum 10 transactions per order.

At least one transaction is required for Alert Matching.

Field	Type	Required	Validation	Description
`reference_id`	string	Always	1-255 chars	Transaction ID (unique within the integration)
`amount_in_cents`	integer	Always	0 to 2147483647	Amount
`currency`	string	Always	ISO 4217	Currency
`payment_method_type`	enum	Always	`CARD`, `STRIPE_LINK`, `BANK_ACCOUNT`, `OTHER`	Payment method
`authorisation_status`	enum	Always	`AUTHORISED`, `CAPTURED`, `SETTLED`, `REVERTED`	Auth status
`payment_method_reference_id`	string	Always	Up to 255 chars. Must be different from the transaction `reference_id`	Payment method ID
`authorised_at`	datetime	For Alert Matching	ISO 8601	Auth timestamp
`descriptor`	string	No	Up to 255 chars	Billing descriptor
`descriptor_prefix`	string	No	Up to 255 chars	Descriptor prefix
`descriptor_suffix`	string	No	Up to 255 chars	Descriptor suffix
`authorisation_code`	string	For Alert Matching (CARD, at least one)	Up to 6 chars	Auth code
`acquirer_reference_number`	string	For Alert Matching (CARD, at least one)	50 chars	ARN
`retrieval_reference_number`	string	No	50 chars	Retrieval reference number (RRN)
`network_id`	string	No	50 chars	Network transaction identifier
`gateway_reference`	string	No	Up to 255 chars	Your payment provider's transaction ID
`settlement_datetime`	datetime	No	ISO 8601	Settlement time
`cvc_verified`	boolean	No	-	CVC verified
`three_d_secure_verified`	boolean	No	-	3DS verified

Card payment fields

When payment_method_type is CARD, the following fields are required:

Field	Type	Required	Description
`payment_method_card_brand`	enum	If `payment_method_type` is `CARD`	`AMEX`, `DINERS`, `DISCOVER`, `EFTPOS_AU`, `JCB`, `MASTERCARD`, `UNIONPAY`, `VISA`, `CARTES_BANCAIRES`, `OTHER`
`payment_method_card_last_4`	string	If `payment_method_type` is `CARD`	Last 4 digits
`payment_method_card_exp_month`	integer	No	Exp month
`payment_method_card_exp_year`	integer	No	Exp year
`payment_method_card_bin`	string	For Alert Matching (at least one identifier)	Card BIN
`payment_method_card_wallet_type`	enum	No	`AMEX_EXPRESS_CHECKOUT`, `APPLE_PAY`, `GOOGLE_PAY`, `LINK`, `MASTERPASS`, `SAMSUNG_PAY`, `VISA_CHECKOUT`, `REVOLUT_PAY`, `OTHER`
`payment_method_card_issuer`	string	No	Card issuer
`payment_method_cardholder_name`	string	No	Name on the card (up to 255 chars)

Note: For alert matching with card payments, send all three identifiers whenever available (acquirer_reference_number, authorisation_code, and payment_method_card_bin). If you cannot provide all three, provide at least one of the following combinations:

acquirer_reference_number (works on its own)

authorisation_code + payment_method_card_last_4

payment_method_card_bin + payment_method_card_last_4 + payment_method_card_brand + amount_in_cents + currency

Billing address

Field	Type	Required	Description
`billing_address.line_1`	string	At least one line required when `billing_address` is provided	Address line 1
`billing_address.line_2`	string	At least one line required when `billing_address` is provided	Address line 2
`billing_address.line_3`	string	At least one line required when `billing_address` is provided	Address line 3
`billing_address.city`	string	Required when `billing_address` is provided	City
`billing_address.country_subdivision`	string	Required when `billing_address` is provided	State/province
`billing_address.postal_code`	string	Required when `billing_address` is provided	Postal code
`billing_address.country`	string	Required when `billing_address` is provided	Country code

Deliveries

Limit: Maximum 10 deliveries per order.

Field	Type	Required	Description
`reference_id`	string	Always	Delivery ID (unique within the integration)
`type`	enum	No	`DIGITAL` or `PHYSICAL`

Create uniqueness scope: On POST, deliveries are unique per integration by reference_id. Reusing a delivery reference_id for the same integration returns DUPLICATE_DELIVERY.

Digital delivery fields

Field	Type	Required	Description
`digital_delivery_datetime`	datetime	No	Delivery time
`digital_download_start_datetime`	datetime	No	Download start
`digital_download_end_datetime`	datetime	No	Download end
`digital_delivery_ip_address`	string	No	Download IP
`digital_notification_sent`	boolean	No	Notification sent
`digital_notification_sent_datetime`	datetime	No	Notification time
`digital_notification_method`	enum	No	`EMAIL`, `SMS`, `PUSH`, `OTHER`

Physical delivery fields

When type is PHYSICAL, the following fields are required:

Field	Type	Required	Description
`physical_shipping_carrier`	string	No	Carrier name
`physical_shipping_tracking_number`	string	No	Tracking number
`physical_shipping_status`	enum	If `type` is `PHYSICAL`	`NOT_SHIPPED`, `BACKORDERED`, `IN_TRANSIT`, `PARTIAL_SHIPPED`, `SHIPPED`, `CANCELLED`, `SHIPPING_EXCEPTION`, `PICKED_UP_BY_CUSTOMER`, `DELIVERED`, `OTHER`
`physical_shipping_status_other_description`	string	If `physical_shipping_status` is `OTHER`	Description when status is OTHER
`physical_shipping_datetime_shipped`	datetime	If `type` is `PHYSICAL`	Ship date
`physical_shipping_datetime_delivered`	datetime	No	Delivery date

Physical shipping address

Field	Type	Required	Description
`physical_shipping_address.line_1`	string	At least one line required when `physical_shipping_address` is provided	Address line 1
`physical_shipping_address.line_2`	string	At least one line required when `physical_shipping_address` is provided	Address line 2
`physical_shipping_address.line_3`	string	At least one line required when `physical_shipping_address` is provided	Address line 3
`physical_shipping_address.city`	string	Required when `physical_shipping_address` is provided	City
`physical_shipping_address.country_subdivision`	string	Required when `physical_shipping_address` is provided	State/province
`physical_shipping_address.postal_code`	string	Required when `physical_shipping_address` is provided	Postal code
`physical_shipping_address.country`	string	Required when `physical_shipping_address` is provided	Country code

Items

Limit: Maximum 10 items per order.

Field	Type	Required	Description
`reference_id`	string	Yes	Item ID (unique within the integration)
`name`	string	Yes	Product name
`price_in_cents`	integer	Yes	Price in cents (≥ 0)
`quantity`	integer	Yes	Quantity (≥ 1)
`product_url`	string	No	Product URL
`product_reference_id`	string	No	Internal product ID
`sku`	string	No	SKU
`delivery_reference_id`	string	No	Links to delivery (must reference a delivery in the same request)
`subscription_reference_id`	string	No	Links to subscription (must reference a subscription in the same request)

Create uniqueness scope: On POST, items are unique per integration by reference_id — across all orders, not per order. Reusing an item reference_id for the same integration returns DUPLICATE_ITEM. Do not use a product-level identifier such as a SKU or a Stripe price ID (price_...) as the item reference_id: two orders containing the same product would collide. Use the line-item identifier (for Stripe, li_...) or a composite key such as <order_reference_id>:<product_id>.

Refunds

Limit: Maximum 10 refunds per order.

Field	Type	Required	Description
`reference_id`	string	Always	Refund ID (unique within the integration)
`amount_in_cents`	integer	Always	Refund amount
`currency`	string	Always	Currency
`status`	enum	Always	`PENDING`, `SUCCEEDED`, `FAILED`
`original_transaction_reference_id`	string	No	Links to transaction
`refund_datetime`	datetime	For CC when enabled	When the refund was processed (ISO 8601)
`retrieval_reference_number`	string	No	Retrieval reference number (RRN), up to 50 chars
`reason`	enum	No	Why the refund was made: `DUPLICATE`, `FRAUDULENT`, `REQUESTED_BY_CUSTOMER`, `OTHER`

Create uniqueness scope: On POST, refunds are unique per integration by reference_id. Reusing a refund reference_id for the same integration returns DUPLICATE_REFUND.

Subscriptions

Limit: Maximum 10 subscriptions per order.

Upsert behaviour: Subscriptions are identified by reference_id per integration. If a subscription with the same reference_id already exists, it will be updated with the new values. The subscription will be linked to the new order while maintaining links to previous orders. This allows the same subscription to span multiple orders (e.g., monthly renewals).

Warning: Full replace semantics - When updating a subscription, ALL optional fields are replaced, not merged. If you omit a field in a subsequent request, it will be set to NULL. For example, if Order 1 creates a subscription with display_name: "Pro Plan" and Order 2 references the same subscription without display_name, the display name will be cleared.

Field	Type	Required	Description
`reference_id`	string	Always	Subscription ID (unique per integration)
`interval`	enum	Always	`DAY`, `WEEK`, `MONTH`, `QUARTER` (3 months), `HALF_YEAR` (6 months), `YEAR`
`interval_price_in_cents`	integer	Always	Price for one interval (for `QUARTER`, the price for one quarter)
`interval_currency`	string	Always	Currency
`status`	enum	No	`ACTIVE`, `CANCELLED`, `TRIALING`, `PAST_DUE`, `PAUSED`
`display_name`	string	No	Display name (up to 255 chars)
`trial_start_date`	datetime	No	Trial start
`trial_end_date`	datetime	No	Trial end
`trial_price_in_cents`	integer	No	Trial price
`trial_currency`	string	No	Trial currency
`start_date`	datetime	No	Subscription start
`cancellation_date`	datetime	No	Cancellation date
`next_charge_date`	datetime	No	Next billing date

Disputes

Limit: Maximum 10 disputes per order.

Field	Type	Required	Description
`reference_id`	string	Always	Dispute ID (unique within the integration)
`amount_in_cents`	integer	Always	Dispute amount
`currency`	string	Always	Currency
`stage`	enum	Always	`1ST_CHARGEBACK`, `2ND_CHARGEBACK`
`status`	enum	Always	`OPEN`, `UNDER_REVIEW`, `WON`, `LOST`
`type`	enum	Always	`INQUIRY`, `CHARGEBACK`
`network_reason_code`	string	No	Network reason code
`is_rapid_dispute_resolution`	boolean	No	RDR flag
`evidence_due_by`	datetime	No	Evidence deadline
`payment_method_type`	enum	No	`CARD`, `KLARNA`, `PAYPAL`
`card_brand`	enum	If `payment_method_type` is `CARD`	`AMEX`, `DINERS`, `DISCOVER`, `EFTPOS_AU`, `JCB`, `MASTERCARD`, `UNIONPAY`, `VISA`, `CARTES_BANCAIRES`, `OTHER`

Create uniqueness scope: On POST, disputes are unique per integration by reference_id. Reusing a dispute reference_id for the same integration returns DUPLICATE_DISPUTE.

Address schema

All address objects (billing, shipping, merchant) use this structure:

Field	Type	Required	Validation
`line_1`	string	At least one line required	Up to 255 chars
`line_2`	string	At least one line required	Up to 255 chars
`line_3`	string	At least one line required	Up to 255 chars
`city`	string	Always	1-255 chars
`country_subdivision`	string	Always	1-255 chars
`postal_code`	string	Always	1-255 chars
`country`	string	Always	ISO 3166-1 alpha-2 uppercase code

Note: When providing an address, include at least one of line_1, line_2, or line_3, plus city, country_subdivision, postal_code, and country.

Field validation

Currency codes

All currency fields must be valid ISO 4217 codes. Common examples: USD, EUR, GBP, CAD, AUD, JPY. See the ISO 4217 standard for the full list.

Phone numbers

Phone fields must be in E.164 format:

Start with +
Followed by 1-15 digits
No spaces or special characters

Valid: +14155551234, +442071234567 Invalid: 415-555-1234, (415) 555-1234

Email addresses

All email fields are validated for proper email format.

Amounts

All *_in_cents fields must be non-negative integers (>= 0).

Reference IDs

In a COMPLETE order, these fields must not share a value: customer_account_id, payment_method_reference_id, and the reference_id of a transaction, refund or dispute. If two of them share a value, the API returns CONFLICTING_REFERENCE_ID.

Two transactions can use the same payment_method_reference_id. An order reference_id can have the same value as a transaction reference_id.

Error codes

Code	Description
`RATE_LIMITED`	Rate limit exceeded (100 requests/min per endpoint)
`BATCH_SIZE_EXCEEDED`	More than 100 orders in request
`CONFLICTING_REFERENCE_ID`	One ID in a `COMPLETE` order is used for two types of object, such as a refund and a transaction
`DUPLICATE_DELIVERY`	Delivery with same `reference_id` already exists for this integration
`DUPLICATE_DELIVERY_REFERENCE`	Duplicate `reference_id` in deliveries array (within same request)
`DUPLICATE_DISPUTE`	Dispute with same `reference_id` already exists for this integration
`DUPLICATE_DISPUTE_REFERENCE`	Duplicate `reference_id` in disputes array (within same request)
`DUPLICATE_ITEM`	Item with same `reference_id` already exists for this integration
`DUPLICATE_ITEM_REFERENCE`	Duplicate `reference_id` in items array (within same request)
`DUPLICATE_ORDER`	Order with same `reference_id` already exists for this integration
`DUPLICATE_REFERENCE_ID`	Fallback error when a duplicate `reference_id` is detected
`DUPLICATE_REFUND`	Refund with same `reference_id` already exists for this integration
`DUPLICATE_REFUND_REFERENCE`	Duplicate `reference_id` in refunds array (within same request)
`DUPLICATE_SUBSCRIPTION_REFERENCE`	Duplicate `reference_id` in subscriptions array (within same request)
`DUPLICATE_TRANSACTION`	Transaction with same `reference_id` already exists for this integration
`DUPLICATE_TRANSACTION_REFERENCE`	Duplicate `reference_id` in transactions array (within same request)
`ENRICHMENT_NOT_ENABLED`	Orders enrichment is not enabled for a non-`CUSTOM_ORDERS` integration when submitting a `PARTIAL` order
`INTERNAL_ERROR`	Internal server error
`INVALID_DELIVERY_REFERENCE`	Item references a non-existent delivery
`INVALID_INTEGRATION`	Integration not found or not accessible
`INVALID_ORDER_TYPE`	Order type doesn't match integration type
`INVALID_PAYMENT_METHOD_REFERENCE`	A transaction's `payment_method_reference_id` is the same as its `reference_id`
`INVALID_SUBSCRIPTION_REFERENCE`	Item references a non-existent subscription
`MISSING_FIELD`	Required field is missing for the configured integration
`DELIVERY_NOT_FOUND`	Referenced delivery not found in order (PATCH only)
`FIELD_NOT_CLEARABLE`	Attempting to clear a stored order field, item field or transaction field with `null` or a blank value (PATCH only)
`IMMUTABLE_FIELD`	Attempting to modify an immutable field: `customer_account_id` after it is set, delivery `type`, `amount_in_cents` or `currency` on an existing refund, dispute or transaction, or dispute `type` (PATCH only)
`INVALID_FIELD_FOR_TYPE`	Updating wrong type fields on delivery (PATCH only)
`ITEM_NOT_FOUND`	The item `reference_id` belongs to another order (PATCH only)
`SUBSCRIPTION_NOT_FOUND`	Referenced subscription not found (PATCH only)
`TRANSACTION_NOT_FOUND`	The transaction `reference_id` belongs to another order (PATCH only)
`TOO_MANY_DELIVERIES`	Maximum 10 deliveries allowed per order
`TOO_MANY_DISPUTES`	Maximum 10 disputes allowed per order
`TOO_MANY_ITEMS`	Maximum 10 items allowed per order
`TOO_MANY_REFUNDS`	Maximum 10 refunds allowed per order
`TOO_MANY_SUBSCRIPTIONS`	Maximum 10 subscriptions allowed per order
`TOO_MANY_TRANSACTIONS`	Maximum 10 transactions allowed per order

Response format

The API uses partial success semantics for per-order processing: valid orders are created even if other orders in the same batch fail. Each order is processed independently, and failures do not cause a rollback of successfully created orders.

This behaviour applies after request schema validation. Schema-level validation failures return a full-request 422 response and skip per-order processing.

HTTP status codes for `POST /v1/orders/`

Status	Meaning	Body shape
`200`	Every order was created, or some orders were created and some failed	`created` / `failed` / `results` / `errors`
`400`	Every order in the batch failed — nothing was created	Same shape as `200`
`422`	The request itself was invalid (schema error, batch size over 100) — no per-order processing happened	`errors` array only
`429`	Rate limited	`errors` array only

Always check errors[], never the status code alone. A 200 response can contain failed orders. Treat a batch as fully processed only when failed is 0. A client that checks only for HTTP 200 will silently drop failed orders.

const response = await fetch("https://api.chargebackstop.com/v1/orders/", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify(orders),
});
const body = await response.json();
if (!response.ok || body.failed > 0) {
  for (const error of body.errors ?? []) {
    // error.index points at the failed order in your request array
    console.error(`order ${error.reference_id} rejected: ${error.code} - ${error.message}`);
  }
}

The response includes:

created: Number of orders successfully created
failed: Number of orders that failed validation
results: Array of successfully created orders
errors: Array of error details for failed orders

Success response

{
  "created": 2,
  "failed": 0,
  "results": [
    {
      "id": "ord_abc123",
      "reference_id": "order-001",
      "type": "COMPLETE",
      "organisation_id": "org_xyz",
      "integration_id": "int_123",
      "created_at": "2024-01-15T10:30:00Z",
      "transactions": [...],
      "items": [...],
      ...,
      "links": [
        {
          "rel": "self",
          "uri": "/v1/orders/ord_abc123"
        }
      ]
    }
  ],
  "errors": []
}

Partial failure response (200)

{
  "created": 1,
  "failed": 1,
  "results": [...],
  "errors": [
    {
      "index": 1,
      "reference_id": "order-002",
      "code": "DUPLICATE_ORDER",
      "message": "Order with reference_id 'order-002' already exists for this integration",
      "field": "reference_id"
    }
  ]
}

Fully-failed batch response (400)

Returned when every order in the batch fails. The body shape is identical to the 200 response; nothing was created.

{
  "created": 0,
  "failed": 1,
  "results": [],
  "errors": [
    {
      "index": 0,
      "reference_id": "order-003",
      "code": "ENRICHMENT_NOT_ENABLED",
      "message": "Orders enrichment is not enabled for this integration",
      "field": "integration_id"
    }
  ]
}

Schema validation response (422)

Returned when the request does not match the schema. No orders are processed, even the valid ones. Each schema error has its own entry in errors:

code is VALIDATION_ followed by the error type, for example VALIDATION_LESS_THAN_EQUAL.
path is where the invalid value is in the request. For the bulk create endpoint, it starts with orders[<index>], where <index> is the position of the order in your request array. path is null when the error applies to the full request body, for example when the body is not an array.
message is <path>: <reason>, or <reason> when path is null. Use path in code; do not parse message.

{
  "errors": [
    {
      "code": "VALIDATION_LESS_THAN_EQUAL",
      "message": "orders[67].transactions[0].amount_in_cents: Input should be less than or equal to 2147483647.",
      "path": "orders[67].transactions[0].amount_in_cents"
    }
  ]
}

Other 422 errors, for example BATCH_SIZE_EXCEEDED, have no path.

Rate-limited response (429)

Returned when you exceed 100 requests per minute for the endpoint.

{
  "errors": [
    {
      "code": "RATE_LIMITED",
      "message": "Too many requests"
    }
  ]
}

Canonical order object

Successful GET /v1/orders, GET /v1/orders/{order_id}, POST /v1/orders, and PATCH /v1/orders/{order_id} responses all use the same canonical order object shape.

Each order object includes:

Core fields: id, reference_id, type, organisation_id, integration_id, created_at
Any documented order, customer, device, and merchant fields that are present for that order
Nested arrays: transactions, deliveries, items, refunds, subscriptions, disputes

Each nested object includes its own server-generated id plus the documented fields for that resource.

PATCH /v1/orders/{order_id} - Update an Order

Partially update an existing order and its nested objects.

Authentication: Bearer token via API key with orders:update ability.

URL parameters:

order_id (required): The order ID to update

Request body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`order_status`	enum	New order status
`order_status_other_description`	string	Required when `order_status` is `OTHER`
`order_communications`	string	Updated communications history
Order, customer, device and merchant fields	various	See Order field updates
`deliveries`	array	Deliveries to create/update (by reference_id)
`items`	array	Items to create/update (by reference_id)
`subscriptions`	array	Subscriptions to update (by reference_id)
`refunds`	array	Refunds to create/update
`disputes`	array	Disputes to create/update
`transactions`	array	Transactions to create/update (by reference_id)

Delivery updates

Update deliveries that belong to the order, or add new ones. Each delivery is identified by reference_id.

Important:

Only deliveries belonging to this order can be updated
To add a delivery, send a new reference_id with type. New deliveries follow the same rules as in POST. See Example 15.
Delivery type (DIGITAL or PHYSICAL) cannot be changed after creation
Fields are type-constrained: digital fields only work on DIGITAL deliveries, physical fields only work on PHYSICAL deliveries

Field	Type	Description
`reference_id`	string	Required. Delivery to update or add
`type`	enum	`DIGITAL` or `PHYSICAL`. Required for a new delivery.
`digital_*` fields	various	For DIGITAL deliveries only
`physical_*` fields	various	For PHYSICAL deliveries only
`physical_shipping_address`	object	Full address object. If provided, it must satisfy the shared address schema.

If you include physical_shipping_address in a PATCH request, send a complete valid address object rather than a partial address fragment.

Example 9: Update physical delivery status

{
  "deliveries": [
    {
      "reference_id": "dlv-001",
      "physical_shipping_status": "DELIVERED",
      "physical_shipping_datetime_delivered": "2024-01-18T14:30:00Z"
    }
  ]
}

Subscription updates

Update existing subscriptions by reference_id. Only subscriptions that already exist can be updated - to create new subscriptions, use the POST endpoint when creating an order.

Field	Type	Required	Description
`reference_id`	string	Yes	Subscription identifier
`interval`	enum	No	`DAY`, `WEEK`, `MONTH`, `QUARTER` (3 months), `HALF_YEAR` (6 months), `YEAR`
`interval_price_in_cents`	integer	No	Price for one interval
`interval_currency`	string	No	ISO 4217 currency code
`status`	enum	No	`ACTIVE`, `CANCELLED`, `TRIALING`, `PAST_DUE`, `PAUSED`
`display_name`	string	No	Display name (up to 255 chars)
Other fields	various	No	See subscription fields in POST documentation

Example 10: Update subscription status

{
  "subscriptions": [
    {
      "reference_id": "sub-001",
      "status": "CANCELLED"
    }
  ]
}

Refund updates

Create new refunds or update existing refunds. For existing refunds, amount_in_cents and currency are immutable, while status, original_transaction_reference_id, refund_datetime, retrieval_reference_number, and reason can be updated. A null or missing value leaves the stored value unchanged.

Field	Type	Required	Description
`reference_id`	string	Yes	Refund identifier
`amount_in_cents`	integer	New only	Refund amount (immutable on existing)
`currency`	string	New only	Currency code (immutable on existing)
`status`	enum	Yes	`PENDING`, `SUCCEEDED`, `FAILED`
`original_transaction_reference_id`	string	No	Related transaction
`refund_datetime`	datetime	No	When the refund was processed (ISO 8601)
`retrieval_reference_number`	string	No	Retrieval reference number (RRN)
`reason`	enum	No	`DUPLICATE`, `FRAUDULENT`, `REQUESTED_BY_CUSTOMER`, `OTHER`

Example 11: Create new refund

{
  "refunds": [
    {
      "reference_id": "ref-001",
      "amount_in_cents": 5000,
      "currency": "USD",
      "status": "SUCCEEDED"
    }
  ]
}

Example 12: Update existing refund status

{
  "refunds": [
    {
      "reference_id": "ref-001",
      "status": "SUCCEEDED"
    }
  ]
}

Dispute updates

Create new disputes or update existing disputes. For existing disputes, amount_in_cents, currency, and type are immutable, while stage, status, network_reason_code, is_rapid_dispute_resolution, evidence_due_by, payment_method_type, and card_brand can be updated.

Field	Type	Required	Description
`reference_id`	string	Yes	Dispute identifier
`amount_in_cents`	integer	New only	Dispute amount (immutable on existing)
`currency`	string	New only	Currency code (immutable on existing)
`type`	enum	New only	`INQUIRY`, `CHARGEBACK` (immutable on existing)
`stage`	enum	Yes	`1ST_CHARGEBACK`, `2ND_CHARGEBACK`
`status`	enum	Yes	`OPEN`, `UNDER_REVIEW`, `WON`, `LOST`
Other fields	various	No	See dispute fields in POST documentation

Example 13: Update dispute status

{
  "disputes": [
    {
      "reference_id": "disp-001",
      "stage": "1ST_CHARGEBACK",
      "status": "WON"
    }
  ]
}

Order field updates

Set or correct these fields on an existing order:

Order: order_number, order_phone, order_request_refund_url, order_buy_again_url, order_write_review_url, order_view_url, order_proof_of_consent, order_is_adult_content
Customer: customer_email, customer_first_name, customer_last_name, customer_account_id, order_email
Device: device_ip_address, device_id, device_fingerprint
Merchant: merchant_reference_id, merchant_name, merchant_contact_email, merchant_customer_service_email, merchant_contact_phone, merchant_store_name, merchant_store_description, merchant_address, merchant_store_url, merchant_url, merchant_terms_and_conditions_url, merchant_logo_url, merchant_refund_policy_url

These fields use the same formats as POST.

Important:

customer_account_id can be set when it is empty. After that it cannot change, and a different value returns IMMUTABLE_FIELD.
Stored values cannot be cleared: null or a blank value returns FIELD_NOT_CLEARABLE. For an empty field, null or a blank value has no effect.
merchant_address replaces the stored address. Address lines that you leave out are removed.
order_datetime, order amounts and order_currency cannot be updated.
Send only data that you recorded for this order. Digital receipts and dispute evidence use these values.

Example 14: Add customer, device and merchant data to an existing order

{
  "order_number": "AUR-100241",
  "customer_email": "casey.jordan@example.com",
  "customer_account_id": "cust-88712",
  "order_email": "casey.jordan@example.com",
  "device_ip_address": "216.24.60.94",
  "device_id": "device-abc123",
  "merchant_name": "Aurora Retail Group",
  "merchant_url": "https://aurora.example.com"
}

Item updates

Add items to the order, or update its existing items. A new reference_id adds an item. Stored item values cannot be cleared.

Field	Type	Required	Description
`reference_id`	string	Yes	Item identifier
`name`	string	New only	Item name
`price_in_cents`	integer	New only	Item price
`quantity`	integer	New only	Item quantity
`delivery_reference_id`	string	No	Delivery in this order to link the item to. It can be a delivery added in the same request.
`subscription_reference_id`	string	No	Subscription in this order to link the item to
`product_url`, `product_reference_id`, `sku`	string	No	See item fields in POST documentation

Example 15: Add a delivery and an item linked to it

{
  "deliveries": [
    {
      "reference_id": "dlv-100241-1",
      "type": "DIGITAL",
      "digital_delivery_datetime": "2024-01-15T10:35:00Z"
    }
  ],
  "items": [
    {
      "reference_id": "item-100241-1",
      "name": "Trail Runner Pro",
      "price_in_cents": 9000,
      "quantity": 1,
      "delivery_reference_id": "dlv-100241-1"
    }
  ]
}

Transaction updates

Add values that you did not have at order creation, such as the ARN, or add a new transaction to the order. A new reference_id adds a transaction, which follows the same rules as in POST, including the validation rules of your integration.

These fields can be updated on an existing transaction: authorisation_status, settlement_datetime, acquirer_reference_number, retrieval_reference_number, authorisation_code, network_id, payment_method_cardholder_name, gateway_reference.

amount_in_cents and currency are immutable on an existing transaction. These fields cannot be cleared, and other fields that you send for an existing transaction are ignored.

Example 16: Add the ARN after settlement

{
  "transactions": [
    {
      "reference_id": "txn-001",
      "authorisation_status": "SETTLED",
      "settlement_datetime": "2024-01-17T12:00:00Z",
      "acquirer_reference_number": "74027012345678901234567"
    }
  ]
}

PATCH error codes

Code	Description
`DELIVERY_NOT_FOUND`	Delivery not found in this order, and the request has no `type` to add it, or the `reference_id` belongs to another order
`DUPLICATE_DELIVERY_REFERENCE`	Duplicate `reference_id` in deliveries array
`DUPLICATE_DISPUTE_REFERENCE`	Duplicate `reference_id` in disputes array
`DUPLICATE_ITEM_REFERENCE`	Duplicate `reference_id` in items array
`DUPLICATE_REFUND_REFERENCE`	Duplicate `reference_id` in refunds array
`DUPLICATE_SUBSCRIPTION_REFERENCE`	Duplicate `reference_id` in subscriptions array
`DUPLICATE_TRANSACTION_REFERENCE`	Duplicate `reference_id` in transactions array
`CONFLICTING_REFERENCE_ID`	The same ID is used for two different entity types, for example a customer and a transaction
`FIELD_NOT_CLEARABLE`	Attempting to clear a stored order field, item field or transaction field with `null` or a blank value
`IMMUTABLE_FIELD`	Attempting to modify an immutable field: `customer_account_id` after it is set, delivery `type`, `amount_in_cents` or `currency` on an existing refund, dispute or transaction, or dispute `type`
`INVALID_DELIVERY_REFERENCE`	Item references a delivery that is not in this order
`INVALID_FIELD_FOR_TYPE`	Updating wrong type fields on delivery (e.g., physical fields on digital delivery)
`INVALID_PAYMENT_METHOD_REFERENCE`	A new transaction's `payment_method_reference_id` is the same as its `reference_id`
`INVALID_SUBSCRIPTION_REFERENCE`	Item references a subscription that is not in this order
`ITEM_NOT_FOUND`	The item `reference_id` belongs to another order
`MISSING_FIELD`	New refund or dispute missing required fields, or a new transaction that does not pass a validation rule of your integration
`SUBSCRIPTION_NOT_FOUND`	Referenced subscription not found
`TOO_MANY_DELIVERIES`	Maximum 10 deliveries allowed per order (including existing + new)
`TOO_MANY_DISPUTES`	Maximum 10 disputes allowed per order (including existing + new)
`TOO_MANY_ITEMS`	Maximum 10 items allowed per order (including existing + new)
`TOO_MANY_REFUNDS`	Maximum 10 refunds allowed per order (including existing + new)
`TOO_MANY_SUBSCRIPTIONS`	Maximum 10 subscriptions allowed per order
`TOO_MANY_TRANSACTIONS`	Maximum 10 transactions allowed per order (including existing + new)
`TRANSACTION_NOT_FOUND`	The transaction `reference_id` belongs to another order
`VALIDATION_*`	A new delivery, item or transaction does not match the POST schema, for example `VALIDATION_MISSING` for a missing field

PATCH response

Returns the updated order with all nested objects.

Success Response (200)

{
  "id": "ord_abc123",
  "reference_id": "order-001",
  "type": "COMPLETE",
  "organisation_id": "org_xyz",
  "integration_id": "int_123",
  "created_at": "2024-01-15T10:30:00Z",
  "order_status": "CLOSED_COMPLETE",
  "transactions": [...],
  "deliveries": [...],
  "items": [...],
  "refunds": [...],
  "subscriptions": [...],
  "disputes": [...],
  "links": [
    {
      "rel": "self",
      "uri": "/v1/orders/ord_abc123"
    }
  ]
}

Error Response (422)

{
  "errors": [
    {
      "code": "IMMUTABLE_FIELD",
      "message": "Cannot modify amount_in_cents on existing refund"
    }
  ]
}

Schema validation errors also return 422, with a path that starts with the request body field, for example transactions[0].amount_in_cents. See Schema validation response (422).

Not Found Response (404)

{
  "detail": "Order with ID ord_nonexistent not found"
}

Orders

GET /v1/orders - List Orders

Query parameters

Example request

Example response

GET /v1/orders/{order_id} - Get Order by ID

URL parameters

Example request

Example response

Error responses

POST /v1/orders - Create Orders

Which mode should I use?

PARTIAL mode - enrichment for existing integrations

Getting started

Digital receipts and deflection field sets

Mastercard Consumer Clarity

Visa Order Insight

Product and merchant information

First-Party Trust (FPT) - Mastercard

Compelling Evidence 3.0 (CE3.0) - Visa

COMPLETE mode

Getting started

Alert matching

Example 8: Full COMPLETE Order

API reference

Order fields

Core fields

Order details

Order URLs

Order evidence

Customer fields

Device fields

Merchant fields

Merchant address

Transactions

Card payment fields

Billing address

Deliveries

Digital delivery fields

Physical delivery fields

Physical shipping address

Items

Refunds

Subscriptions

Disputes

Address schema

Field validation

Currency codes

Phone numbers

Email addresses

Amounts

Reference IDs

Error codes

Response format

HTTP status codes for POST /v1/orders/

Success response

Partial failure response (200)

Fully-failed batch response (400)

Schema validation response (422)

Rate-limited response (429)

Canonical order object

PATCH /v1/orders/{order_id} - Update an Order

Request body

Delivery updates

Subscription updates

Refund updates

Dispute updates

Order field updates

Item updates

Transaction updates

PATCH error codes

PATCH response

HTTP status codes for `POST /v1/orders/`