Orders

Order management endpoints

List orders

get

Retrieve a paginated list of orders

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Query parameters

pageintegerOptional

Page number

Example: 1

per_pageinteger · max: 100Optional

Items per page (max 100)

Example: 25

includestringOptional

Comma-separated list of expansions: fields, integrations, items, payments, subscriptions, paymentplans, customer, affiliate

Example: fields,integrations

filter[id]stringOptional

Filter by id (exact match)

filter[id.gte]stringOptional

Filter by id (greater than or equal)

filter[id.lte]stringOptional

Filter by id (less than or equal)

filter[customer_id]stringOptional

Filter by customer_id (exact match)

filter[customer_id.gte]stringOptional

Filter by customer_id (greater than or equal)

filter[customer_id.lte]stringOptional

Filter by customer_id (less than or equal)

filter[checkout_publish_id]stringOptional

Filter by checkout_publish_id (exact match)

filter[checkout_publish_id.gte]stringOptional

Filter by checkout_publish_id (greater than or equal)

filter[checkout_publish_id.lte]stringOptional

Filter by checkout_publish_id (less than or equal)

filter[status]stringOptional

Filter by status (exact match)

filter[status.contains]stringOptional

Filter by status (contains)

filter[currency]stringOptional

Filter by currency (exact match)

filter[currency.contains]stringOptional

Filter by currency (contains)

filter[display_total]stringOptional

Filter by display_total (exact match)

filter[display_total.gte]stringOptional

Filter by display_total (greater than or equal)

filter[display_total.lte]stringOptional

Filter by display_total (less than or equal)

filter[promo_id]stringOptional

Filter by promo_id (exact match)

filter[promo_id.gte]stringOptional

Filter by promo_id (greater than or equal)

filter[promo_id.lte]stringOptional

Filter by promo_id (less than or equal)

filter[created_at]stringOptional

Filter by created_at (exact match)

filter[updated_at]stringOptional

Filter by updated_at (exact match)

sortstringOptional

Sort field (prefix with - for descending)

Example: -created_at

Responses

200

Successful response with paginated list

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

get

/v2/orders/

HTTPcURLJavaScriptPython

GET /v2/orders/ HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": 123,
      "customer_id": 12345,
      "checkout_publish_id": 1,
      "card_id": 1,
      "checkoutview_id": null,
      "gateway_id": null,
      "user_id": null,
      "account_address_id": null,
      "url_token": null,
      "currency": "USD",
      "display_total": 9999,
      "shipping_country": "US",
      "shipping_zip": "10001",
      "shipping_state": "NY",
      "shipping_city": "New York",
      "shipping_street2": "Apt 4B",
      "shipping_street1": "123 Main St",
      "billing_country": "US",
      "billing_zip": "10001",
      "billing_state": "NY",
      "billing_city": "New York",
      "billing_street2": null,
      "billing_street1": null,
      "phone_number": "[phone]",
      "user_agent": null,
      "terms_signed_at": null,
      "privacy_policy_signed_at": null,
      "marketing_opted_in_at": null,
      "is_apple_pay": false,
      "is_rollback": true,
      "is_captcha": true,
      "promo_id": null,
      "internal_name": null,
      "is_google_pay": false,
      "offer_name": null,
      "ip": "192.168.1.1",
      "is_customer_prefilled": null,
      "affiliate_cookies": null,
      "headers": null,
      "event_ready_at": null,
      "published_block_item_ids": [
        1
      ],
      "preserved_params": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "detail": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "payment_status": "succeeded",
      "stepkeys": [
        {
          "id": 1,
          "order_id": 1,
          "status": "accepted",
          "url_slug": null,
          "session_key": null,
          "created_at": null,
          "updated_at": null
        }
      ],
      "checkout": null,
      "card": null,
      "gateway": null,
      "promo": null,
      "user": null,
      "checkoutview": null,
      "account_address": null,
      "items": [
        {
          "id": 456,
          "order_id": 123,
          "name": "Premium Widget",
          "base_price": 2999,
          "tax_type": "vat",
          "tax_rate": 0.0825,
          "is_commissionable": null,
          "is_refunded_by_spiffy": null,
          "published_checkout_item_id": null,
          "sort_order": null,
          "product_option_price_id": null,
          "parent_id": null,
          "published_block_item_id": null,
          "replace_published_block_item_id": null,
          "block_type": null,
          "offset_type": null,
          "replace_price_id": null,
          "is_skipped": true,
          "event_ready_at": null,
          "created_at": null,
          "updated_at": null,
          "payment_ids": [
            1
          ],
          "discounts": [
            {
              "id": 1,
              "order_item_id": 1,
              "promo_id": 1,
              "discount_type": "amount",
              "discount_offset": null,
              "use_taxes": null,
              "created_at": null,
              "updated_at": null,
              "promo_code": null
            }
          ]
        }
      ],
      "payments": [
        {
          "id": 789,
          "order_id": 123,
          "source_id": null,
          "source": {
            "id": 1,
            "card_id": 1,
            "gateway_id": 1,
            "stripe_source_id": null,
            "stripe_paymentmethod_id": null,
            "paypal_billing_agreement_id": null,
            "created_at": null,
            "updated_at": null,
            "stripe_customer_id": null,
            "paypal_payer_id": null,
            "paypal_customer_id": null,
            "paypal_token_id": null,
            "nmi_customer_vault_id": null,
            "authentication": null,
            "customer_id": 1,
            "is_active": true,
            "is_three_d_secure_supported": true,
            "type": null,
            "last_four": null,
            "exp_month": null,
            "exp_year": null,
            "address_zip": null,
            "country": null,
            "fingerprint": null,
            "cardholder_name_first": null,
            "cardholder_name_last": null,
            "address_street1": null,
            "address_street2": null,
            "address_city": null,
            "address_state": null,
            "address_country": null,
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "gateway_id": null,
          "initial_payment_id": null,
          "stripe_charge_id": "ch_1abc123",
          "stripe_invoice_id": null,
          "stripe_paymentintent_id": "pi_1abc123",
          "paypal_order_id": null,
          "paypal_capture_id": null,
          "is_manual": null,
          "is_3ds_in_progress": true,
          "amount": 4999,
          "amount_paid": 4999,
          "amount_refunded": 0,
          "currency": "USD",
          "failure_reason": null,
          "has_pending_retry": true,
          "refunded_at": null,
          "status": "succeeded",
          "is_3ds": true,
          "can_skip": true,
          "nmi_transaction_id": null,
          "is_startup_fee": true,
          "failure_code": null,
          "created_at": null,
          "updated_at": null,
          "attempts": [
            {
              "id": 1,
              "status": "text",
              "failure_reason": null,
              "created_at": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "subscriptions": [
        {
          "id": 1,
          "order_item_id": 1,
          "product_option_price_id": 1,
          "card_id": 1,
          "swapped_from_id": null,
          "published_block_item_id": null,
          "replace_published_block_item_id": null,
          "name": null,
          "block_type": null,
          "stripe_subscription_id": null,
          "stripe_subscription_item_id": null,
          "status": "active",
          "next_payment_at": null,
          "trial_days": 1,
          "num_payment_skips_remaining": 1,
          "tax_rate": 0.0825,
          "is_commissionable": null,
          "is_trial_end_upcoming_sent": null,
          "unpaid_at": null,
          "canceled_at": null,
          "order_id": null,
          "tax_type": null,
          "replace_price_id": null,
          "published_checkout_item_id": null,
          "event_ready_at": null,
          "created_at": null,
          "updated_at": null,
          "payment_ids": [
            1
          ],
          "retry_schedule": [
            "text"
          ],
          "current_payment_status": null,
          "detail": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "discounts": [
            {
              "promo_code": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "usage": null,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "paymentplans": [
        {
          "id": 1,
          "order_id": 1,
          "card_id": 1,
          "status": "active",
          "next_payment_at": null,
          "frequency": "month",
          "frequency_count": 1,
          "is_finance_hidden": null,
          "unpaid_at": null,
          "is_scheduled": true,
          "created_at": null,
          "updated_at": null,
          "item_ids": [
            1
          ],
          "current_payment_status": null,
          "payment_ids": [
            1
          ],
          "retry_schedule": [
            "text"
          ],
          "detail": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "customer": null,
      "affiliate": null,
      "program": null,
      "fields": [],
      "integrations": null,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "pages": 6
  }
}

Update order fields

patch

Update order core and custom fields

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Body

application/json

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

patch

/v2/orders/{id}

HTTPcURLJavaScriptPython

PATCH /v2/orders/{id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "fields": [
    {
      "field_id": "text",
      "field_name": "text",
      "field_type": "text",
      "value": null
    }
  ]
}

No content

Refund order

post

Issue a full or partial refund for an order

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Body

application/json

do_affiliate_adjustmentbooleanOptional

notesstringOptional

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

post

/v2/orders/{id}/refund

HTTPcURLJavaScriptPython

POST /v2/orders/{id}/refund HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "do_affiliate_adjustment": true,
  "notes": "text"
}

No content

Add note to order

post

Add a note to order activity history

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Body

application/json

notesstring · min: 1Required

Responses

201

Created successfully

application/json

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

post

/v2/orders/{id}/notes

HTTPcURLJavaScriptPython

POST /v2/orders/{id}/notes HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "notes": "text"
}

No content

Cancel order item

patch

Mark an order item as canceled

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

order_idstringRequired

Order ID

item_idstringRequired

Order item ID to cancel

Body

application/json

is_refunded_by_spiffybooleanRequired

notesstringOptional

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

patch

/v2/orders/{order_id}/items/{item_id}/canceled

HTTPcURLJavaScriptPython

PATCH /v2/orders/{order_id}/items/{item_id}/canceled HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "is_refunded_by_spiffy": true,
  "notes": "text"
}

No content

Get affiliate commissions

get

Get commission details for an affiliate on an order

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

order_idstringRequired

Order ID

affiliate_idstringRequired

Affiliate ID

program_idstringRequired

Affiliate program ID

Responses

200

Successful response

application/json

anyOptional

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

500

Internal Server Error - An unexpected error occurred

application/json

get

/v2/orders/{order_id}/affiliate/{affiliate_id}/program/{program_id}

HTTPcURLJavaScriptPython

GET /v2/orders/{order_id}/affiliate/{affiliate_id}/program/{program_id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update order affiliate

put

Update affiliate commission settings for an order

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

order_idstringRequired

Order ID

affiliate_idstringRequired

Affiliate ID

program_idstringRequired

Affiliate program ID

Body

application/json

no_retro_commissionsbooleanOptional

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

put

/v2/orders/{order_id}/affiliate/{affiliate_id}/program/{program_id}

HTTPcURLJavaScriptPython

PUT /v2/orders/{order_id}/affiliate/{affiliate_id}/program/{program_id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "no_retro_commissions": true
}

No content

Remove order affiliate

delete

Remove affiliate attribution from an order

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

order_idstringRequired

Order ID

Responses

204

Deleted successfully

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

500

Internal Server Error - An unexpected error occurred

application/json

delete

/v2/orders/{order_id}/affiliate

HTTPcURLJavaScriptPython

DELETE /v2/orders/{order_id}/affiliate HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content