API Reference / Endpoints

Orders

Orders represent one-time purchases. Creating an order immediately processes payment through the EPD Gateway — there is no separate "charge" step.

Order Lifecycle

POST /orders → pending → succeeded ✓
                        → failed ✗

After a successful order, you can issue full or partial refunds:

POST /orders/:id/refund → partially_refunded → refunded

Important: Orders are immutable financial records. There are no update or delete endpoints. All modifications happen through refunds.

POST /orders

Create an order

Creates a new order and immediately processes payment through the EPD Gateway. There is no separate "charge" step — creating the order is the charge.

How It Works

  1. Validate customer and payment method exist
  2. Look up product prices from the database (prevents price manipulation)
  3. Create order record with status pending
  4. Submit payment to EPD Gateway
  5. Update order status to succeeded or failed
  6. Return the complete order with inline transaction details

Price Security

The price field is not accepted in order items. Prices are always resolved from the product catalog to prevent client-side price manipulation. If you need custom pricing, create a product with the desired price first.

Idempotency

This endpoint requires an idempotency key (X-EPD-Idempotency-Key header). If the same key is sent again within 24 hours, the original order is returned without creating a duplicate charge.

Tip: Always use idempotency keys for order creation. Network timeouts can leave you uncertain whether the payment went through — replaying with the same key safely returns the original result.

Header parameters

NameTypeDescription
EPD-Version
string
API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.
e.g. "2026-02-11"
X-EPD-Idempotency-Keyrequired
string (uuid)
UUID v4 idempotency key. Same key with same request returns cached response. Keys expire after 24 hours.
e.g. "550e8400-e29b-41d4-a716-446655440000"

Request body required

FieldTypeDescription
customer_idrequired
string
ID of the customer placing the order.
e.g. "550e8400-e29b-41d4-a716-446655440000"
payment_method_idrequired
string
ID of the payment method to charge.
e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430c8"
itemsrequired
array[object]
Line items for the order. **Note:** Price is not accepted in items — always uses the product's current price to prevent price manipulation.
currency
string
Three-letter ISO 4217 currency code (lowercase).
e.g. "usd"
description
string
Description for this order.
e.g. "Premium coaching bundle purchase"
shipping_address_id
string (uuid)
ID of an existing shipping address to use.
e.g. "6ba7b818-9dad-11d1-80b4-00c04fd430c8"
shipping_address
object
Create a new shipping address for this order.
first_namerequired
string
e.g. "John"
last_namerequired
string
e.g. "Doe"
address_line1required
string
e.g. "123 Main St"
address_line2
string
e.g. "Suite 100"
cityrequired
string
e.g. "San Francisco"
staterequired
string
e.g. "CA"
postal_coderequired
string
e.g. "94105"
countryrequired
string
Two-letter ISO 3166-1 alpha-2 country code (uppercase).
e.g. "US"
phone
string
Phone number in E.164 format.
e.g. "+14155551234"
metadata
Metadata
coupon_code
string
Optional coupon code to apply at order creation. Case-insensitive. For product-scoped coupons the discount applies only to eligible cart items. Invalid or ineligible codes return a `400` with a structured `error.code` (e.g. `coupon_expired`, `product_not_eligible`).
e.g. "SAVE10"

Code samples

curl -X POST https://api.epd.com/v1/orders \
  -H "Authorization: Bearer epd_test_sk_xxxx" \
  -H "Content-Type: application/json" \
  -H "EPD-Version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "payment_method_id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8",
    "items": [
      { "product_id": "6ba7b810-9dad-11d1-80b4-00c04fd430d1", "quantity": 2 }
    ],
    "currency": "usd",
    "metadata": { "campaign": "summer_sale" }
  }'
const response = await fetch('https://api.epd.com/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer epd_test_sk_xxxx',
    'Content-Type': 'application/json',
    'EPD-Version': '2026-02-11',
    'X-EPD-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    customer_id: '550e8400-e29b-41d4-a716-446655440000',
    payment_method_id: '6ba7b815-9dad-11d1-80b4-00c04fd430c8',
    items: [
      { product_id: '6ba7b810-9dad-11d1-80b4-00c04fd430d1', quantity: 2 },
    ],
    currency: 'usd',
  }),
});

const order = await response.json();
console.log(order.status); // "succeeded" or "failed"
import uuid
import requests

response = requests.post(
    'https://api.epd.com/v1/orders',
    headers={
        'Authorization': 'Bearer epd_test_sk_xxxx',
        'EPD-Version': '2026-02-11',
        'X-EPD-Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'customer_id': '550e8400-e29b-41d4-a716-446655440000',
        'payment_method_id': '6ba7b815-9dad-11d1-80b4-00c04fd430c8',
        'items': [
            {'product_id': '6ba7b810-9dad-11d1-80b4-00c04fd430d1', 'quantity': 2},
        ],
        'currency': 'usd',
    }
)

order = response.json()
print(order['status'])  # "succeeded" or "failed"
$ch = curl_init('https://api.epd.com/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer epd_test_sk_xxxx',
        'Content-Type: application/json',
        'EPD-Version: 2026-02-11',
        'X-EPD-Idempotency-Key: ' . wp_generate_uuid4(),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'customer_id' => '550e8400-e29b-41d4-a716-446655440000',
        'payment_method_id' => '6ba7b815-9dad-11d1-80b4-00c04fd430c8',
        'items' => [
            ['product_id' => '6ba7b810-9dad-11d1-80b4-00c04fd430d1', 'quantity' => 2],
        ],
        'currency' => 'usd',
    ]),
]);

$order = json_decode(curl_exec($ch), true);
echo $order['status']; // "succeeded" or "failed"

Responses

201 Order created and payment processed.
FieldTypeDescription
idrequired
string
e.g. "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
order_numberrequired
string
8-character alphanumeric order number.
e.g. "1A2B3C4D"
customer_idrequired
string
e.g. "550e8400-e29b-41d4-a716-446655440002"
statusrequired
enum
pendingsucceededfailedvoidedpartially_refundedrefundedrefund_failedchargebackchargeback_acceptedchargeback_dismissed
e.g. "succeeded"
itemsrequired
array[OrderItem]
subtotalrequired
integer
Subtotal in cents (sum of line items before discounts).
e.g. 5998
discount_amountrequired
integer
Discount applied to this order in cents (`0` when no coupon was used). Equals `subtotal - total` for orders without additional adjustments.
e.g. 600
totalrequired
integer
Total amount in cents (net of any discount).
e.g. 5398
currencyrequired
string
e.g. "usd"
descriptionnullable
string
applied_couponrequired
object
Coupon details captured at redemption time. `null` when no coupon was applied.
idrequired
string (uuid)
e.g. "6ba7b820-9dad-11d1-80b4-00c04fd430c8"
coderequired
string
e.g. "SAVE10"
namerequired
string
e.g. "Holiday Promo"
kindrequired
enum
generatedpromo
e.g. "promo"
percentagenullable
number
Percent discount (0–100) for percentage coupons; `null` for amount-off coupons.
e.g. 10
amountnullable
integer
Amount-off in cents for amount-off coupons; `null` for percentage coupons.
e.g. null
max_discount_amountnullable
integer
Maximum discount cap in cents, frozen at redemption time. Only applies to percentage-off coupons (always `null` for amount-off). Mirrors the snapshot stored on the redemption row, so historical orders keep their original cap even if the live coupon's cap is later edited.
e.g. 500
currencyrequired
string
e.g. "usd"
durationrequired
enum
oncerepeatingforever
e.g. "once"
duration_in_cyclesnullable
integer
e.g. null
discount_amountrequired
integer
Discount applied to this order in cents.
e.g. 600
payment_methodnullable
object
id
string
e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430d3"
card_last_four
string
e.g. "4242"
card_brand
string
e.g. "visa"
transactions
array[OrderTransaction]
shipping_addressnullable
object
id
string (uuid)
first_name
string
last_name
string
address_line1
string
address_line2nullable
string
city
string
state
string
postal_code
string
country
string
phonenullable
string
metadata
Metadata
failure_reasonnullable
string
created_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
updated_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
400 Bad Request — The request was invalid or cannot be served.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
401 Unauthorized — Authentication failed.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
404 Not Found — The requested resource doesn't exist.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
429 Too Many Requests — Rate limit exceeded.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
GET /orders

List all orders

Returns a paginated list of orders sorted by creation date (newest first). Supports filtering by customer, status, date range, and amount range.

Common Queries

Use Case Query
All successful orders ?status=succeeded
Orders for a customer ?customer_id=550e8400-e29b-41d4-a716-446655440000
Orders this month ?created_at[gte]=2024-02-01&created_at[lt]=2024-03-01
High-value orders ?total[gte]=10000 (orders $100+)
Refunded orders ?status=refunded,partially_refunded

Query parameters

NameTypeDescription
limit
integer
Number of items to return per page.
Default: 10
starting_after
string
Cursor for forward pagination. Returns items created after this ID.
e.g. "550e8400-e29b-41d4-a716-446655440000"
ending_before
string
Cursor for backward pagination. Returns items created before this ID.
e.g. "550e8400-e29b-41d4-a716-446655440001"
sort
string
Sort order. Format: `field[direction]` or `-field` for descending. Default: `created_at[desc]`.
e.g. "created_at[desc]"
customer_id
string
Filter by customer ID.
e.g. "550e8400-e29b-41d4-a716-446655440000"
status
string
Filter by status (comma-separated for multiple): `pending`, `succeeded`, `failed`, `voided`, `partially_refunded`, `refunded`.
e.g. "succeeded"
created_at[gte]
string
Filter by creation date (on or after, ISO 8601).
e.g. "2024-01-01"
created_at[lt]
string
Filter by creation date (before, ISO 8601).
e.g. "2024-02-01"
total[gte]
integer
Minimum total in cents.
e.g. 1000
total[lte]
integer
Maximum total in cents.
e.g. 100000
expand
string
Expand: `customer`, `items`, `transactions`.
e.g. "customer"
fields[orders]
string
Sparse fieldsets — comma-separated (e.g., `id,status,total,created`).
e.g. "id,status,total,created"

Header parameters

NameTypeDescription
EPD-Version
string
API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.
e.g. "2026-02-11"

Code samples

# All successful orders this month
curl "https://api.epd.com/v1/orders?status=succeeded&created_at[gte]=2024-02-01" \
  -H "Authorization: Bearer epd_test_sk_xxxx"

# Orders for a specific customer
curl "https://api.epd.com/v1/orders?customer_id=550e8400-e29b-41d4-a716-446655440000&limit=50" \
  -H "Authorization: Bearer epd_test_sk_xxxx"
// List successful orders with expanded customer
const params = new URLSearchParams({
  status: 'succeeded',
  'created_at[gte]': '2024-02-01',
  expand: 'customer',
  limit: '50',
});

const response = await fetch(
  `https://api.epd.com/v1/orders?${params}`,
  { headers: { 'Authorization': 'Bearer epd_test_sk_xxxx' } }
);

const { data: orders, has_more } = await response.json();

Responses

200 A paginated list of orders.
FieldTypeDescription
data
array[Order]
url
any
e.g. "/v1/orders"
401 Unauthorized — Authentication failed.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
GET /orders/{id}

Retrieve an order

Retrieves the full details of an order including line items, payment method, and transaction history. Use expand to include the customer object inline.

Path parameters

NameTypeDescription
idrequired
string
Order ID (UUID).
e.g. "6ba7b811-9dad-11d1-80b4-00c04fd430c8"

Query parameters

NameTypeDescription
expand
string
Expand: `customer`, `transactions`.

Header parameters

NameTypeDescription
EPD-Version
string
API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.
e.g. "2026-02-11"

Code samples

curl https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8 \
  -H "Authorization: Bearer epd_test_sk_xxxx"
const response = await fetch(
  'https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8?expand=customer',
  { headers: { 'Authorization': 'Bearer epd_test_sk_xxxx' } }
);

const order = await response.json();
console.log(order.status);       // "succeeded"
console.log(order.total / 100);  // 59.98

Responses

200 The order with full details.
FieldTypeDescription
idrequired
string
e.g. "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
order_numberrequired
string
8-character alphanumeric order number.
e.g. "1A2B3C4D"
customer_idrequired
string
e.g. "550e8400-e29b-41d4-a716-446655440002"
statusrequired
enum
pendingsucceededfailedvoidedpartially_refundedrefundedrefund_failedchargebackchargeback_acceptedchargeback_dismissed
e.g. "succeeded"
itemsrequired
array[OrderItem]
subtotalrequired
integer
Subtotal in cents (sum of line items before discounts).
e.g. 5998
discount_amountrequired
integer
Discount applied to this order in cents (`0` when no coupon was used). Equals `subtotal - total` for orders without additional adjustments.
e.g. 600
totalrequired
integer
Total amount in cents (net of any discount).
e.g. 5398
currencyrequired
string
e.g. "usd"
descriptionnullable
string
applied_couponrequired
object
Coupon details captured at redemption time. `null` when no coupon was applied.
idrequired
string (uuid)
e.g. "6ba7b820-9dad-11d1-80b4-00c04fd430c8"
coderequired
string
e.g. "SAVE10"
namerequired
string
e.g. "Holiday Promo"
kindrequired
enum
generatedpromo
e.g. "promo"
percentagenullable
number
Percent discount (0–100) for percentage coupons; `null` for amount-off coupons.
e.g. 10
amountnullable
integer
Amount-off in cents for amount-off coupons; `null` for percentage coupons.
e.g. null
max_discount_amountnullable
integer
Maximum discount cap in cents, frozen at redemption time. Only applies to percentage-off coupons (always `null` for amount-off). Mirrors the snapshot stored on the redemption row, so historical orders keep their original cap even if the live coupon's cap is later edited.
e.g. 500
currencyrequired
string
e.g. "usd"
durationrequired
enum
oncerepeatingforever
e.g. "once"
duration_in_cyclesnullable
integer
e.g. null
discount_amountrequired
integer
Discount applied to this order in cents.
e.g. 600
payment_methodnullable
object
id
string
e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430d3"
card_last_four
string
e.g. "4242"
card_brand
string
e.g. "visa"
transactions
array[OrderTransaction]
shipping_addressnullable
object
id
string (uuid)
first_name
string
last_name
string
address_line1
string
address_line2nullable
string
city
string
state
string
postal_code
string
country
string
phonenullable
string
metadata
Metadata
failure_reasonnullable
string
created_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
updated_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
404 Not Found — The requested resource doesn't exist.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
POST /orders/{id}/refund

Refund an order

Processes a refund for an order through the EPD Gateway. Supports both full and partial refunds.

Refund Types

Type How Result
Full refund Omit amount Refunds entire remaining balance, status → refunded
Partial refund Provide amount in cents Refunds specified amount, status → partially_refunded

Multiple Partial Refunds

You can issue multiple partial refunds on the same order. The total of all refunds cannot exceed the original order amount.

Eligible Orders

Only orders with status succeeded or partially_refunded can be refunded. Attempting to refund an order in any other status returns a 400 error.

Tip: The response includes the full order with an updated transactions array showing the refund transaction. Check transactions for the refund's processor_transaction_id for reconciliation.

Path parameters

NameTypeDescription
idrequired
string
Order ID (UUID).
e.g. "6ba7b811-9dad-11d1-80b4-00c04fd430c8"

Header parameters

NameTypeDescription
EPD-Version
string
API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.
e.g. "2026-02-11"
X-EPD-Idempotency-Keyrequired
string (uuid)
UUID v4 idempotency key. Same key with same request returns cached response. Keys expire after 24 hours.
e.g. "550e8400-e29b-41d4-a716-446655440000"

Request body

FieldTypeDescription
amount
integer
Amount to refund in cents. Omit for a full refund of the remaining balance.
e.g. 2999

Code samples

# Full refund
curl -X POST https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8/refund \
  -H "Authorization: Bearer epd_test_sk_xxxx" \
  -H "Content-Type: application/json" \
  -H "EPD-Version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)"

# Partial refund ($29.99)
curl -X POST https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8/refund \
  -H "Authorization: Bearer epd_test_sk_xxxx" \
  -H "Content-Type: application/json" \
  -H "EPD-Version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)" \
  -d '{ "amount": 2999 }'
// Full refund
const response = await fetch('https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8/refund', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer epd_test_sk_xxxx',
    'Content-Type': 'application/json',
    'EPD-Version': '2026-02-11',
    'X-EPD-Idempotency-Key': crypto.randomUUID(),
  },
});

const order = await response.json();
console.log(order.status); // "refunded"

// Partial refund ($29.99)
const partial = await fetch('https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430d0/refund', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer epd_test_sk_xxxx',
    'Content-Type': 'application/json',
    'X-EPD-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ amount: 2999 }),
});
import uuid
import requests

# Full refund
response = requests.post(
    'https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430c8/refund',
    headers={
        'Authorization': 'Bearer epd_test_sk_xxxx',
        'EPD-Version': '2026-02-11',
        'X-EPD-Idempotency-Key': str(uuid.uuid4()),
    }
)

order = response.json()
print(order['status'])  # "refunded"

# Partial refund ($29.99)
response = requests.post(
    'https://api.epd.com/v1/orders/6ba7b811-9dad-11d1-80b4-00c04fd430d0/refund',
    headers={
        'Authorization': 'Bearer epd_test_sk_xxxx',
        'X-EPD-Idempotency-Key': str(uuid.uuid4()),
    },
    json={'amount': 2999}
)

Responses

200 Refund processed. Returns the updated order with refund transaction.
FieldTypeDescription
idrequired
string
e.g. "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
order_numberrequired
string
8-character alphanumeric order number.
e.g. "1A2B3C4D"
customer_idrequired
string
e.g. "550e8400-e29b-41d4-a716-446655440002"
statusrequired
enum
pendingsucceededfailedvoidedpartially_refundedrefundedrefund_failedchargebackchargeback_acceptedchargeback_dismissed
e.g. "succeeded"
itemsrequired
array[OrderItem]
subtotalrequired
integer
Subtotal in cents (sum of line items before discounts).
e.g. 5998
discount_amountrequired
integer
Discount applied to this order in cents (`0` when no coupon was used). Equals `subtotal - total` for orders without additional adjustments.
e.g. 600
totalrequired
integer
Total amount in cents (net of any discount).
e.g. 5398
currencyrequired
string
e.g. "usd"
descriptionnullable
string
applied_couponrequired
object
Coupon details captured at redemption time. `null` when no coupon was applied.
idrequired
string (uuid)
e.g. "6ba7b820-9dad-11d1-80b4-00c04fd430c8"
coderequired
string
e.g. "SAVE10"
namerequired
string
e.g. "Holiday Promo"
kindrequired
enum
generatedpromo
e.g. "promo"
percentagenullable
number
Percent discount (0–100) for percentage coupons; `null` for amount-off coupons.
e.g. 10
amountnullable
integer
Amount-off in cents for amount-off coupons; `null` for percentage coupons.
e.g. null
max_discount_amountnullable
integer
Maximum discount cap in cents, frozen at redemption time. Only applies to percentage-off coupons (always `null` for amount-off). Mirrors the snapshot stored on the redemption row, so historical orders keep their original cap even if the live coupon's cap is later edited.
e.g. 500
currencyrequired
string
e.g. "usd"
durationrequired
enum
oncerepeatingforever
e.g. "once"
duration_in_cyclesnullable
integer
e.g. null
discount_amountrequired
integer
Discount applied to this order in cents.
e.g. 600
payment_methodnullable
object
id
string
e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430d3"
card_last_four
string
e.g. "4242"
card_brand
string
e.g. "visa"
transactions
array[OrderTransaction]
shipping_addressnullable
object
id
string (uuid)
first_name
string
last_name
string
address_line1
string
address_line2nullable
string
city
string
state
string
postal_code
string
country
string
phonenullable
string
metadata
Metadata
failure_reasonnullable
string
created_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
updated_atrequired
string (date-time)
e.g. "2024-01-15T10:30:00.000Z"
400 Bad Request — The request was invalid or cannot be served.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
401 Unauthorized — Authentication failed.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
404 Not Found — The requested resource doesn't exist.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.