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:readfor GET endpointsorders:writefor POST endpointsorders:updatefor 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
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
Example response
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
order_id
string
The internal order ID (e.g., ord_abc123)
Example request
Example response
Returns the full order object with all nested relations (transactions, deliveries, items, refunds, subscriptions, disputes).
Error responses
404 Not Found - Order does not exist or is not accessible:
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
422and no orders are processed.
Which mode should I use?
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_ORDERSintegrations. Attempting to create a COMPLETE order on a Stripe, Adyen, or other payment processor integration will returnINVALID_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:writeability
Minimal required fields:
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
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:
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)
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:
items
Array with at least one item containing name
Example 3: Order Insight (Visa)
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:
items[].name
Product name
items[].price_in_cents
Item price
items[].quantity
Quantity ordered
Merchant information fields:
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
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:
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)
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:
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)
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_ORDERSintegrationAPI key with
orders:writeability
Required fields for COMPLETE orders:
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:
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:
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):
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)
Example 8: Full COMPLETE Order
This example includes all available fields for a COMPLETE order.
API reference
Required column abbreviations:
CC
Consumer Clarity (Mastercard)
FPT
First Party Trust (Mastercard)
OI
Order Insight (Visa)
CE3.0
Compelling Evidence 3.0 (Visa)
Order fields
Core fields
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
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
1-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
order_request_refund_url
string
No
URL, 1-255 chars
Refund request URL
order_buy_again_url
string
No
URL, 1-255 chars
Reorder URL
order_write_review_url
string
No
URL, 1-255 chars
Review URL
order_view_url
string
No
URL, 1-255 chars
Order view URL
Order evidence
order_proof_of_consent
string
No
1-500 chars
Proof of customer consent
order_communications
string
No
1-1000 chars
Communications history
Customer fields
customer_email
string
For FPT, CE3.0
Valid email
Customer's email
customer_first_name
string
No
1-255 chars
First name
customer_last_name
string
No
1-255 chars
Last name
customer_account_id
string
PARTIAL orders
1-255 chars
Customer identifier
order_email
string
PARTIAL orders, and for FPT when enabled
Valid email
Order email
Device fields
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)
1-255 chars
Device ID
device_fingerprint
string
PARTIAL orders, and for FPT/CE3.0 when enabled (at least one)
1-255 chars
Device fingerprint
At least one device identifier is required for PARTIAL orders, and for FPT/CE3.0 when enabled.
Merchant fields
merchant_reference_id
string
No
1-255 chars
Internal merchant reference
merchant_name
string
When default merchant not configured
1-255 chars
Corporate name
merchant_store_name
string
When default merchant not configured
1-255 chars
Store name
merchant_store_description
string
No
1-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
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.
reference_id
string
Always
1-255 chars
Transaction ID (unique within the integration)
amount_in_cents
integer
Always
>= 0
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
1-255 chars
Payment method ID
authorised_at
datetime
For Alert Matching
ISO 8601
Auth timestamp
descriptor
string
No
1-255 chars
Billing descriptor
descriptor_prefix
string
No
1-255 chars
Descriptor prefix
descriptor_suffix
string
No
1-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
network_id
string
No
50 chars
Network transaction identifier
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:
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
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_4payment_method_card_bin+payment_method_card_last_4+payment_method_card_brand+amount_in_cents+currency
Billing address
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.
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
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:
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
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.
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)
Refunds
Limit: Maximum 10 refunds per order.
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
No
When the refund was processed (ISO 8601)
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.
reference_id
string
Always
Subscription ID (unique per integration)
interval
enum
Always
DAY, WEEK, MONTH, YEAR
interval_price_in_cents
integer
Always
Price per interval
interval_currency
string
Always
Currency
status
enum
No
ACTIVE, CANCELLED, TRIALING, PAST_DUE
display_name
string
No
Display name
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.
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:
line_1
string
At least one line required
1-255 chars
line_2
string
At least one line required
1-255 chars
line_3
string
At least one line required
1-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
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).
Error codes
RATE_LIMITED
Rate limit exceeded (100 requests/min per endpoint)
BATCH_SIZE_EXCEEDED
More than 100 orders in request
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_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)
IMMUTABLE_FIELD
Attempting to modify immutable field on existing refund/dispute (PATCH only)
INVALID_FIELD_FOR_TYPE
Updating wrong type fields on delivery (PATCH only)
SUBSCRIPTION_NOT_FOUND
Referenced subscription not found (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.
The response includes:
created: Number of orders successfully createdfailed: Number of orders that failed validationresults: Array of successfully created orderserrors: Array of error details for failed orders
Success response
Error response
Rate-limited response (429)
Returned when you exceed 100 requests per minute for the endpoint.
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.
order_status
enum
New order status
order_status_other_description
string
Required when order_status is OTHER
order_communications
string
Updated communications history
deliveries
array
Deliveries to update (by reference_id)
subscriptions
array
Subscriptions to update (by reference_id)
refunds
array
Refunds to create/update
disputes
array
Disputes to create/update
Delivery updates
Update deliveries that belong to the order. Each delivery is identified by reference_id.
Important:
Only deliveries belonging to this order can be updated
Delivery type (
DIGITALorPHYSICAL) cannot be changed after creationFields are type-constrained: digital fields only work on
DIGITALdeliveries, physical fields only work onPHYSICALdeliveries
reference_id
string
Required. Delivery to update
digital_* fields
various
For DIGITAL deliveries only
physical_* fields
various
For PHYSICAL deliveries only
physical_shipping_address
object
Partial address - only provided fields are updated
Example 9: Update physical delivery status
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.
reference_id
string
Yes
Subscription identifier
interval
enum
No
DAY, WEEK, MONTH, YEAR
interval_price_in_cents
integer
No
Price per interval
interval_currency
string
No
ISO 4217 currency code
status
enum
No
ACTIVE, CANCELLED, TRIALING, PAST_DUE
display_name
string
No
Display name
Other fields
various
No
See subscription fields in POST documentation
Example 10: Update subscription status
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, and refund_datetime can be updated.
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)
Example 11: Create new refund
Example 12: Update existing refund status
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.
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
PATCH error codes
DELIVERY_NOT_FOUND
Referenced delivery not found in this order
DUPLICATE_DELIVERY_REFERENCE
Duplicate reference_id in deliveries array
DUPLICATE_DISPUTE_REFERENCE
Duplicate reference_id in disputes array
DUPLICATE_REFUND_REFERENCE
Duplicate reference_id in refunds array
DUPLICATE_SUBSCRIPTION_REFERENCE
Duplicate reference_id in subscriptions array
IMMUTABLE_FIELD
Attempting to modify amount/currency on existing refund/dispute
INVALID_FIELD_FOR_TYPE
Updating wrong type fields on delivery (e.g., physical fields on digital delivery)
MISSING_FIELD
New refund/dispute missing required fields
SUBSCRIPTION_NOT_FOUND
Referenced subscription not found
TOO_MANY_DELIVERIES
Maximum 10 deliveries allowed per order
TOO_MANY_DISPUTES
Maximum 10 disputes 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
PATCH response
Returns the updated order with all nested objects.
Success Response (200)
Error Response (422)
Not Found Response (404)
Was this helpful?