> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/models.md).

# Models

## The Error401 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The Error403 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The Error500 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The CustomerResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"CustomerResponse":{"type":"object","properties":{"id":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Unique customer identifier"},"account_id":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Account ID this customer belongs to"},"email":{"type":"string","nullable":true,"maxLength":255,"format":"email","description":"Customer email address"},"name_first":{"type":"string","nullable":true,"maxLength":255,"description":"Customer first name"},"name_last":{"type":"string","nullable":true,"maxLength":255,"description":"Customer last name"},"company_name":{"type":"string","nullable":true,"maxLength":255,"description":"Company name (for business customers)"},"tax_id":{"type":"string","nullable":true,"maxLength":255,"description":"Tax identification number"},"locale":{"type":"string","nullable":true,"maxLength":10,"description":"BCP 47 locale the customer most recently requested (source of truth for comms)"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when customer was created"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when customer was last updated"},"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardResponse"},"description":"Customer payment cards (included via ?include=cards)"},"fields":{"type":"array","items":{"nullable":true},"description":"Custom fields (included via ?include=fields)"},"stats":{"$ref":"#/components/schemas/CustomerStats"},"integrations":{"type":"object","additionalProperties":{"nullable":true},"description":"Integration-specific data (included via ?include=integrations)"}},"required":["id","account_id"]},"CardResponse":{"type":"object","properties":{"id":{"type":"integer","description":"Unique card identifier"},"customer_id":{"type":"integer","description":"ID of the customer who owns this card"},"is_active":{"type":"boolean","nullable":true,"description":"Whether the card is active and can be used for payments"},"is_three_d_secure_supported":{"type":"boolean","nullable":true,"description":"Whether the card supports 3D Secure authentication"},"type":{"type":"string","nullable":true,"maxLength":255,"description":"Card brand/type"},"last_four":{"type":"string","nullable":true,"maxLength":255,"description":"Last four digits of the card number"},"exp_month":{"type":"string","nullable":true,"maxLength":255,"description":"Expiration month (2 digits)"},"exp_year":{"type":"string","nullable":true,"maxLength":255,"description":"Expiration year (4 digits)"},"address_zip":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address ZIP/postal code"},"country":{"type":"string","nullable":true,"maxLength":255,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"maxLength":255,"description":"Unique card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"maxLength":255,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"maxLength":255,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address city"},"address_state":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address state/province"},"address_country":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address country code"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when card was added"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when card was last updated"},"is_in_use":{"type":"boolean","description":"Whether card is used by active subscriptions or payment plans"},"active_subscription_count":{"type":"integer","description":"Number of active subscriptions using this card"},"active_paymentplan_count":{"type":"integer","description":"Number of active payment plans using this card"},"gateway_id":{"type":"integer","nullable":true,"description":"Gateway ID from the latest card source"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentMethod ID from the latest card source"},"stripe_customer_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe Customer ID from the latest card source"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal billing agreement ID from the latest card source"},"paypal_payer_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal payer ID from the latest card source"},"paypal_customer_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal customer ID from the latest card source"},"paypal_token_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal token ID from the latest card source"},"is_incompatible":{"type":"boolean","description":"Whether this card is incompatible with the subscription due to different Stripe customer ID"},"is_test_broken":{"type":"boolean","description":"Always false in production; internal QA use only."}},"required":["id","customer_id","is_in_use","active_subscription_count","active_paymentplan_count"]},"CustomerStats":{"type":"object","properties":{"sales_count":{"type":"integer","description":"Total number of completed sales/orders"},"sales_amount":{"type":"number","description":"Total sales amount in dollars"},"active_subscription_count":{"type":"integer","description":"Number of active subscriptions"},"unpaid_subscription_count":{"type":"integer","description":"Number of subscriptions with unpaid invoices"},"payment_plan_in_progress_count":{"type":"integer","description":"Number of active payment plans"}},"description":"Customer statistics (included via ?include=stats)"}}}}
```

## The CardResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"CardResponse":{"type":"object","properties":{"id":{"type":"integer","description":"Unique card identifier"},"customer_id":{"type":"integer","description":"ID of the customer who owns this card"},"is_active":{"type":"boolean","nullable":true,"description":"Whether the card is active and can be used for payments"},"is_three_d_secure_supported":{"type":"boolean","nullable":true,"description":"Whether the card supports 3D Secure authentication"},"type":{"type":"string","nullable":true,"maxLength":255,"description":"Card brand/type"},"last_four":{"type":"string","nullable":true,"maxLength":255,"description":"Last four digits of the card number"},"exp_month":{"type":"string","nullable":true,"maxLength":255,"description":"Expiration month (2 digits)"},"exp_year":{"type":"string","nullable":true,"maxLength":255,"description":"Expiration year (4 digits)"},"address_zip":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address ZIP/postal code"},"country":{"type":"string","nullable":true,"maxLength":255,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"maxLength":255,"description":"Unique card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"maxLength":255,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"maxLength":255,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address city"},"address_state":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address state/province"},"address_country":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address country code"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when card was added"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when card was last updated"},"is_in_use":{"type":"boolean","description":"Whether card is used by active subscriptions or payment plans"},"active_subscription_count":{"type":"integer","description":"Number of active subscriptions using this card"},"active_paymentplan_count":{"type":"integer","description":"Number of active payment plans using this card"},"gateway_id":{"type":"integer","nullable":true,"description":"Gateway ID from the latest card source"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentMethod ID from the latest card source"},"stripe_customer_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe Customer ID from the latest card source"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal billing agreement ID from the latest card source"},"paypal_payer_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal payer ID from the latest card source"},"paypal_customer_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal customer ID from the latest card source"},"paypal_token_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal token ID from the latest card source"},"is_incompatible":{"type":"boolean","description":"Whether this card is incompatible with the subscription due to different Stripe customer ID"},"is_test_broken":{"type":"boolean","description":"Always false in production; internal QA use only."}},"required":["id","customer_id","is_in_use","active_subscription_count","active_paymentplan_count"]}}}}
```

## The CustomerStats object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"CustomerStats":{"type":"object","properties":{"sales_count":{"type":"integer","description":"Total number of completed sales/orders"},"sales_amount":{"type":"number","description":"Total sales amount in dollars"},"active_subscription_count":{"type":"integer","description":"Number of active subscriptions"},"unpaid_subscription_count":{"type":"integer","description":"Number of subscriptions with unpaid invoices"},"payment_plan_in_progress_count":{"type":"integer","description":"Number of active payment plans"}},"description":"Customer statistics (included via ?include=stats)"}}}}
```

## The Customer object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Customer":{"type":"object","properties":{"id":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Unique customer identifier"},"account_id":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Account ID this customer belongs to"},"email":{"type":"string","nullable":true,"maxLength":255,"format":"email","description":"Customer email address"},"name_first":{"type":"string","nullable":true,"maxLength":255,"description":"Customer first name"},"name_last":{"type":"string","nullable":true,"maxLength":255,"description":"Customer last name"},"company_name":{"type":"string","nullable":true,"maxLength":255,"description":"Company name (for business customers)"},"tax_id":{"type":"string","nullable":true,"maxLength":255,"description":"Tax identification number"},"locale":{"type":"string","nullable":true,"maxLength":10,"description":"BCP 47 locale the customer most recently requested (source of truth for comms)"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when customer was created"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when customer was last updated"}},"required":["id","account_id"]}}}}
```

## The Error404 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The Error400 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The Error409 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Error409":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}
```

## The Order object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Order":{"type":"object","properties":{"id":{"type":"integer","description":"Unique order identifier"},"customer_id":{"type":"integer","description":"Customer who placed the order"},"checkout_publish_id":{"type":"integer","description":"Published checkout ID"},"card_id":{"type":"integer","description":"Payment card ID used"},"checkoutview_id":{"type":"integer","nullable":true,"description":"Checkout view ID"},"gateway_id":{"type":"integer","nullable":true,"description":"Payment gateway ID"},"user_id":{"type":"integer","nullable":true,"description":"Admin user who created order (if manual)"},"account_address_id":{"type":"integer","nullable":true,"description":"Account address ID"},"url_token":{"type":"string","nullable":true,"maxLength":255,"description":"Unique URL token for order"},"currency":{"type":"string","nullable":true,"enum":["aud","cad","usd","gbp","eur","sgd","aed","afn","all","amd","ang","aoa","ars","awg","azn","bam","bbd","bdt","bgn","bif","bmd","bnd","bob","brl","bsd","bwp","bzd","cdf","chf","clp","cny","cop","crc","cve","czk","djf","dkk","dop","dzd","egp","etb","fjd","fkp","gel","gip","gmd","gnf","gtq","gyd","hkd","hnl","hrk","htg","huf","idr","ils","inr","isk","jmd","jpy","kes","kgs","khr","kmf","krw","kyd","kzt","lak","lbp","lkr","lrd","lsl","mad","mdl","mga","mkd","mmk","mnt","mop","mro","mur","mvr","mwk","mxn","myr","mzn","nad","ngn","nio","nok","npr","nzd","pab","pen","pgk","php","pkr","pln","pyg","qar","ron","rsd","rub","rwf","sar","sbd","scr","sek","shp","sll","sos","srd","std","szl","thb","tjs","top","try","ttd","twd","tzs","uah","ugx","uyu","uzs","vnd","vuv","wst","xaf","xcd","xof","xpf","yer","zar","zmw",null],"description":"Order currency code"},"display_total":{"type":"integer","description":"Total order amount in cents"},"shipping_country":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping country code"},"shipping_zip":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping ZIP/postal code"},"shipping_state":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping state/province"},"shipping_city":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping city"},"shipping_street2":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping address line 2"},"shipping_street1":{"type":"string","nullable":true,"maxLength":255,"description":"Shipping address line 1"},"billing_country":{"type":"string","nullable":true,"maxLength":255,"description":"Billing country code"},"billing_zip":{"type":"string","nullable":true,"maxLength":255,"description":"Billing ZIP/postal code"},"billing_state":{"type":"string","nullable":true,"maxLength":255,"description":"Billing state/province"},"billing_city":{"type":"string","nullable":true,"maxLength":255,"description":"Billing city"},"billing_street2":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 2"},"billing_street1":{"type":"string","nullable":true,"maxLength":255,"description":"Billing address line 1"},"phone_number":{"type":"string","nullable":true,"maxLength":255,"description":"Customer phone number"},"user_agent":{"type":"string","nullable":true,"description":"Browser user agent string"},"terms_signed_at":{"type":"string","nullable":true,"format":"date-time","description":"When terms were accepted"},"privacy_policy_signed_at":{"type":"string","nullable":true,"format":"date-time","description":"When privacy policy was accepted"},"marketing_opted_in_at":{"type":"string","nullable":true,"format":"date-time","description":"When customer opted into marketing"},"is_apple_pay":{"type":"boolean","description":"Whether order used Apple Pay"},"is_rollback":{"type":"boolean","description":"Whether order is a rollback"},"is_captcha":{"type":"boolean","description":"Whether CAPTCHA was completed"},"promo_id":{"type":"integer","nullable":true,"description":"Promotion ID applied"},"promo_code_id":{"type":"integer","nullable":true,"description":"promo_codes.id redeemed by this order (unique-mode promotions)."},"internal_name":{"type":"string","nullable":true,"maxLength":255,"description":"Internal order name/reference"},"is_google_pay":{"type":"boolean","description":"Whether order used Google Pay"},"offer_name":{"type":"string","nullable":true,"maxLength":255,"description":"Offer/campaign name"},"ip":{"type":"string","nullable":true,"maxLength":255,"description":"Customer IP address"},"is_customer_prefilled":{"type":"boolean","nullable":true,"description":"Whether customer data was pre-filled"},"affiliate_cookies":{"type":"string","nullable":true,"description":"Affiliate tracking cookie data (JSON)"},"event_ready_at":{"type":"string","nullable":true,"format":"date-time","description":"When order event was ready"},"published_block_item_ids":{"type":"array","nullable":true,"items":{"type":"integer"},"description":"Array of published block item IDs"},"preserved_params":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Preserved URL parameters"},"locale":{"type":"string","nullable":true,"maxLength":10,"description":"BCP 47 locale code captured at checkout"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Order creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"detail":{"type":"object","additionalProperties":{"nullable":true},"description":"Calculated order summary (subtotal, tax, total, etc.)"},"payment_status":{"type":"string","description":"Computed payment status"},"stepkeys":{"type":"array","items":{"$ref":"#/components/schemas/OrderStepkey"},"description":"Order stepkeys (completion status)"},"checkout":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Checkout configuration"},"card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment card details (without sources)"},"gateway":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment gateway info"},"promo":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Promo code data"},"user":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"User who created order (if manual)"},"checkoutview":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Checkout view data"},"account_address":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Account address data"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"},"description":"Order items (expansion: items)"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/OrderPayment"},"description":"Order payments (expansion: payments)"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"},"description":"Subscriptions (expansion: subscriptions)"},"paymentplans":{"type":"array","items":{"$ref":"#/components/schemas/Paymentplan"},"description":"Payment plans (expansion: paymentplans)"},"customer":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Customer data with cards (expansion: customer)"},"affiliate":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Affiliate data (expansion: affiliate)"},"program":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Affiliate program data (expansion: affiliate)"},"fields":{"anyOf":[{"type":"array","items":{"nullable":true}},{"type":"object","additionalProperties":{"nullable":true}},{"nullable":true}],"description":"Order fields array (expansion: fields)"},"integrations":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Integration attributes (expansion: integrations)"}},"required":["id","customer_id","checkout_publish_id","card_id"]},"OrderStepkey":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"status":{"type":"string","enum":["pending","accepted","declined","expired","in_progress"],"description":"Order completion status"},"url_slug":{"type":"string","nullable":true,"maxLength":255,"description":"URL slug for order completion page"},"session_key":{"type":"string","nullable":true,"maxLength":255,"description":"Session key for order completion"},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","order_id"]},"OrderItem":{"type":"object","properties":{"id":{"type":"integer","description":"Order item ID"},"order_id":{"type":"integer","description":"Associated order ID"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Item name/description"},"base_price":{"type":"integer","description":"Base price in cents"},"tax_type":{"type":"string","nullable":true,"enum":["vat","tax","gst",null],"description":"Type of tax applied"},"tax_rate":{"type":"number","nullable":true,"description":"Tax rate as decimal"},"is_commissionable":{"type":"boolean","nullable":true,"description":"Whether this item generates affiliate commission"},"is_refunded_by_spiffy":{"type":"boolean","nullable":true,"description":"Whether refund is handled by Spiffy"},"published_checkout_item_id":{"type":"integer","nullable":true,"description":"Source checkout item ID"},"sort_order":{"type":"integer","nullable":true,"description":"Display order"},"product_option_price_id":{"type":"integer","nullable":true,"description":"Product option price ID"},"parent_id":{"type":"integer","nullable":true,"description":"Parent item ID (for nested items)"},"published_block_item_id":{"type":"integer","nullable":true,"description":"Block item ID"},"replace_published_block_item_id":{"type":"integer","nullable":true,"description":"Replacement block item ID"},"block_type":{"type":"string","nullable":true,"maxLength":255,"description":"Block type identifier"},"offset_type":{"type":"string","nullable":true,"description":"Offset type for billing"},"replace_price_id":{"type":"integer","nullable":true,"description":"Replacement price ID"},"is_skipped":{"type":"boolean","description":"Whether this item was skipped"},"event_ready_at":{"type":"string","nullable":true,"format":"date-time","description":"Event readiness timestamp"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Array of payment IDs for this item"},"discounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_item_id":{"type":"integer"},"promo_id":{"type":"integer"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount applied"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount amount (cents) or percentage"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"},"promo_code":{"type":"string","nullable":true,"description":"Promo code string"}},"required":["id","order_item_id","promo_id"]},"description":"Discounts applied to this item"}},"required":["id","order_id"]},"OrderPayment":{"type":"object","properties":{"id":{"type":"integer","description":"Payment ID"},"order_id":{"type":"integer","description":"Associated order ID"},"customer_id":{"type":"integer","nullable":true,"description":"Customer who made the payment (sourced from the parent order; included for convenience so customer-centric reporting doesn't require a second hop through /v2/orders)"},"source_id":{"type":"integer","nullable":true,"description":"Payment source (card) ID (database field)"},"source":{"type":"object","properties":{"id":{"type":"integer","description":"Payment source ID"},"card_id":{"type":"integer","description":"Customer card ID"},"gateway_id":{"type":"integer","description":"Payment gateway ID"},"stripe_source_id":{"type":"string","nullable":true,"description":"Stripe source ID"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"description":"Stripe payment method ID"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"description":"PayPal billing agreement ID"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"stripe_customer_id":{"type":"string","nullable":true,"description":"Stripe customer ID"},"paypal_payer_id":{"type":"string","nullable":true,"description":"PayPal payer ID"},"paypal_customer_id":{"type":"string","nullable":true,"description":"PayPal customer ID"},"paypal_token_id":{"type":"string","nullable":true,"description":"PayPal token ID"},"nmi_customer_vault_id":{"type":"string","nullable":true,"description":"NMI customer vault ID"},"authentication":{"nullable":true,"description":"3D Secure authentication data"},"customer_id":{"type":"integer","description":"Customer ID who owns this source"},"is_active":{"type":"boolean","description":"Whether this source is active"},"is_three_d_secure_supported":{"type":"boolean","description":"Whether 3D Secure is supported"},"type":{"type":"string","nullable":true,"description":"Card brand (visa, mastercard, etc.)"},"last_four":{"type":"string","nullable":true,"description":"Last 4 digits of card number"},"exp_month":{"type":"string","nullable":true,"description":"Expiration month (MM)"},"exp_year":{"type":"string","nullable":true,"description":"Expiration year (YYYY)"},"address_zip":{"type":"string","nullable":true,"description":"Card billing ZIP/postal code"},"country":{"type":"string","nullable":true,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"description":"Card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"description":"Billing city"},"address_state":{"type":"string","nullable":true,"description":"Billing state/province"},"address_country":{"type":"string","nullable":true,"description":"Billing country code"}},"required":["id","card_id","gateway_id","customer_id"],"description":"Payment source (card) object"},"gateway_id":{"type":"integer","nullable":true,"description":"Payment gateway ID"},"initial_payment_id":{"type":"integer","nullable":true,"description":"Initial payment ID (for retries)"},"stripe_charge_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe charge ID"},"stripe_invoice_id":{"type":"string","nullable":true,"description":"Stripe invoice ID"},"stripe_paymentintent_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentIntent ID"},"paypal_order_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal order ID"},"paypal_capture_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal capture ID"},"is_manual":{"type":"boolean","nullable":true,"description":"Whether payment was manually recorded"},"is_3ds_in_progress":{"type":"boolean","description":"Whether 3D Secure authentication is in progress"},"amount":{"type":"integer","description":"Total payment amount in cents"},"amount_paid":{"type":"integer","description":"Amount successfully paid in cents"},"amount_refunded":{"type":"integer","description":"Amount refunded in cents"},"currency":{"type":"string","nullable":true,"enum":["aud","cad","usd","gbp","eur","sgd","aed","afn","all","amd","ang","aoa","ars","awg","azn","bam","bbd","bdt","bgn","bif","bmd","bnd","bob","brl","bsd","bwp","bzd","cdf","chf","clp","cny","cop","crc","cve","czk","djf","dkk","dop","dzd","egp","etb","fjd","fkp","gel","gip","gmd","gnf","gtq","gyd","hkd","hnl","hrk","htg","huf","idr","ils","inr","isk","jmd","jpy","kes","kgs","khr","kmf","krw","kyd","kzt","lak","lbp","lkr","lrd","lsl","mad","mdl","mga","mkd","mmk","mnt","mop","mro","mur","mvr","mwk","mxn","myr","mzn","nad","ngn","nio","nok","npr","nzd","pab","pen","pgk","php","pkr","pln","pyg","qar","ron","rsd","rub","rwf","sar","sbd","scr","sek","shp","sll","sos","srd","std","szl","thb","tjs","top","try","ttd","twd","tzs","uah","ugx","uyu","uzs","vnd","vuv","wst","xaf","xcd","xof","xpf","yer","zar","zmw",null],"description":"Payment currency code"},"failure_reason":{"type":"string","nullable":true,"description":"Human-readable failure reason"},"has_pending_retry":{"type":"boolean","description":"Whether a retry is pending"},"refunded_at":{"type":"string","nullable":true,"format":"date-time","description":"Refund timestamp"},"status":{"type":"string","nullable":true,"enum":["pending","succeeded","failed","refunded","disputed","dispute_refunded",null],"description":"Payment status"},"is_3ds":{"type":"boolean","description":"Whether 3D Secure was used"},"can_skip":{"type":"boolean","description":"Whether payment can be skipped"},"nmi_transaction_id":{"type":"string","nullable":true,"maxLength":255,"description":"NMI transaction ID"},"is_startup_fee":{"type":"boolean","description":"Whether this is a startup/setup fee"},"failure_code":{"type":"string","nullable":true,"maxLength":255,"description":"Gateway-specific failure code"},"payment_method_type":{"type":"string","nullable":true,"maxLength":255,"description":"What actually paid this charge, as the gateway reports it (e.g. card, apple_pay, klarna, afterpay_clearpay). Null when unknown or not recorded — clients should fall back to the card display."},"financing_installments_count":{"type":"integer","nullable":true,"description":"Number of installments for a financing (BNPL) payment. Null for non-financing payments."},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"initial_payment_id":{"type":"integer","nullable":true},"amount":{"type":"integer"},"amount_paid":{"type":"integer"},"amount_refunded":{"type":"integer"},"currency":{"type":"string","nullable":true},"status":{"type":"string"},"failure_reason":{"type":"string","nullable":true},"has_pending_retry":{"type":"boolean","nullable":true},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id"]},"description":"Payment retry attempts"}},"required":["id","order_id","amount_paid"]},"Subscription":{"type":"object","properties":{"id":{"type":"integer","description":"Subscription ID"},"order_item_id":{"type":"integer","description":"Associated order item ID"},"product_option_price_id":{"type":"integer","description":"Product option price ID"},"card_id":{"type":"integer","description":"Payment card ID"},"swapped_from_id":{"type":"integer","nullable":true,"description":"Previous subscription ID if swapped"},"published_block_item_id":{"type":"integer","nullable":true,"description":"Published block item ID"},"replace_published_block_item_id":{"type":"integer","nullable":true,"description":"Replacement block item ID"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Subscription name/description"},"block_type":{"type":"string","nullable":true,"maxLength":255,"description":"Block type identifier"},"stripe_subscription_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription ID"},"stripe_subscription_item_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription item ID"},"status":{"type":"string","enum":["pending","trialing","active","past_due","canceling","canceled","unpaid","swapped"],"description":"Subscription status"},"next_payment_at":{"type":"string","nullable":true,"format":"date-time","description":"Next scheduled payment date"},"trial_days":{"type":"integer","description":"Trial period duration in days"},"num_payment_skips_remaining":{"type":"integer","description":"Number of payment skips remaining"},"tax_rate":{"type":"number","nullable":true,"description":"Tax rate as decimal"},"is_commissionable":{"type":"boolean","nullable":true,"description":"Whether subscription generates affiliate commission"},"is_trial_end_upcoming_sent":{"type":"boolean","nullable":true,"description":"Whether trial end notification was sent"},"unpaid_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription became unpaid"},"canceled_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription was canceled"},"order_id":{"type":"integer","nullable":true,"description":"Associated order ID"},"tax_type":{"type":"string","nullable":true,"description":"Type of tax (vat, tax, gst)"},"replace_price_id":{"type":"integer","nullable":true,"description":"Replacement price ID"},"published_checkout_item_id":{"type":"string","nullable":true,"maxLength":255,"description":"Published checkout item ID"},"event_ready_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription event was ready"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Array of payment IDs (excluding initial payment)"},"retry_schedule":{"type":"array","items":{"type":"string"},"description":"Pending retry schedule for past_due subscriptions (array of date strings)"},"current_payment_status":{"type":"string","nullable":true,"description":"Status of most recent payment"},"detail":{"type":"object","additionalProperties":{"nullable":true},"description":"Calculated subscription details (pricing, totals)"},"discounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Discount ID"},"subscription_id":{"type":"integer","description":"Associated subscription ID"},"promo_id":{"type":"integer","description":"Promotion ID"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"stripe_coupon_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe coupon ID"},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount (fixed amount or percentage)"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount value (cents for amount, percentage for percent)"},"duration_in_months":{"type":"integer","description":"Duration of discount in months"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"deactivated_at":{"type":"string","nullable":true,"format":"date-time","description":"When the discount was deactivated"},"promo_code":{"type":"string","nullable":true,"description":"Promo code from related promo"}},"required":["id","subscription_id","promo_id"]},"description":"Discounts applied to subscription"},"usage":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Usage data from payment gateway"},"payments":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Subscription payments (expansion: payments)"},"custom_fields":{"type":"array","items":{"nullable":true},"description":"Custom fields (expansion: custom_fields)"},"customer":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Customer data (expansion: customer)"},"order":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Order data (expansion: order)"},"price":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Product option price with nested option and product"},"card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment card associated with this subscription"},"gateway":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment gateway used for this subscription"}},"required":["id","order_item_id","product_option_price_id","card_id"]},"Paymentplan":{"type":"object","properties":{"id":{"type":"integer","description":"Payment plan ID"},"order_id":{"type":"integer","description":"Associated order ID"},"card_id":{"type":"integer","description":"Card used for payments"},"status":{"type":"string","enum":["active","past_due","unpaid","completed","defaulted"],"description":"Payment plan status. 'defaulted' is a terminal write-off state set via the pay endpoint with payoff_outcome='defaulted'."},"next_payment_at":{"type":"string","nullable":true,"format":"date-time","description":"Next scheduled payment date"},"finished_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when the plan reached a terminal state (completed or defaulted). Null for active plans."},"frequency":{"type":"string","enum":["day","week","month","year"],"description":"Payment frequency"},"frequency_count":{"type":"integer","description":"Frequency multiplier (e.g., 2 for bi-weekly)"},"is_finance_hidden":{"type":"boolean","nullable":true,"description":"Whether finance details are hidden"},"unpaid_at":{"type":"string","nullable":true,"format":"date-time","description":"When payment plan became unpaid"},"is_scheduled":{"type":"boolean","description":"Whether plan is scheduled"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"remaining_balance":{"type":"integer","description":"Remaining balance in cents"},"paid_amount":{"type":"integer","description":"Total paid amount in cents"},"total_amount":{"type":"integer","description":"Total plan amount in cents"},"defaulted_amount":{"type":"integer","description":"Magnitude of write-off adjustments tied to this plan from a payoff_outcome='defaulted' request, in cents (positive). Zero for plans that were never defaulted."},"payments_made":{"type":"integer","description":"Number of payments made"},"payments_remaining":{"type":"integer","description":"Number of payments remaining"},"item_ids":{"type":"array","items":{"type":"integer"},"description":"Order item IDs in this plan"},"current_payment_status":{"type":"string","nullable":true,"description":"Status of most recent payment"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Payment IDs for this plan"},"retry_schedule":{"type":"array","items":{"type":"string"},"description":"Pending retry schedule for past_due plans (array of date strings)"},"detail":{"type":"object","additionalProperties":{"nullable":true},"description":"Calculated payment plan details"},"items":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Payment plan items (expansion: items)"},"payments":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Payments for this plan (expansion: payments)"},"order":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Order data (expansion: order)"},"customer":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Customer data (expansion: customer)"},"custom_fields":{"type":"array","items":{"nullable":true},"description":"Custom fields (expansion: custom_fields)"},"card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment card (expansion: card)"},"gateway":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment gateway info (expansion: gateway)"}},"required":["id","order_id","card_id","status","frequency"]}}}}
```

## The OrderStepkey object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"OrderStepkey":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"status":{"type":"string","enum":["pending","accepted","declined","expired","in_progress"],"description":"Order completion status"},"url_slug":{"type":"string","nullable":true,"maxLength":255,"description":"URL slug for order completion page"},"session_key":{"type":"string","nullable":true,"maxLength":255,"description":"Session key for order completion"},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","order_id"]}}}}
```

## The OrderItem object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"OrderItem":{"type":"object","properties":{"id":{"type":"integer","description":"Order item ID"},"order_id":{"type":"integer","description":"Associated order ID"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Item name/description"},"base_price":{"type":"integer","description":"Base price in cents"},"tax_type":{"type":"string","nullable":true,"enum":["vat","tax","gst",null],"description":"Type of tax applied"},"tax_rate":{"type":"number","nullable":true,"description":"Tax rate as decimal"},"is_commissionable":{"type":"boolean","nullable":true,"description":"Whether this item generates affiliate commission"},"is_refunded_by_spiffy":{"type":"boolean","nullable":true,"description":"Whether refund is handled by Spiffy"},"published_checkout_item_id":{"type":"integer","nullable":true,"description":"Source checkout item ID"},"sort_order":{"type":"integer","nullable":true,"description":"Display order"},"product_option_price_id":{"type":"integer","nullable":true,"description":"Product option price ID"},"parent_id":{"type":"integer","nullable":true,"description":"Parent item ID (for nested items)"},"published_block_item_id":{"type":"integer","nullable":true,"description":"Block item ID"},"replace_published_block_item_id":{"type":"integer","nullable":true,"description":"Replacement block item ID"},"block_type":{"type":"string","nullable":true,"maxLength":255,"description":"Block type identifier"},"offset_type":{"type":"string","nullable":true,"description":"Offset type for billing"},"replace_price_id":{"type":"integer","nullable":true,"description":"Replacement price ID"},"is_skipped":{"type":"boolean","description":"Whether this item was skipped"},"event_ready_at":{"type":"string","nullable":true,"format":"date-time","description":"Event readiness timestamp"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Array of payment IDs for this item"},"discounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_item_id":{"type":"integer"},"promo_id":{"type":"integer"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount applied"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount amount (cents) or percentage"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"},"promo_code":{"type":"string","nullable":true,"description":"Promo code string"}},"required":["id","order_item_id","promo_id"]},"description":"Discounts applied to this item"}},"required":["id","order_id"]}}}}
```

## The OrderItemDiscount object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"OrderItemDiscount":{"type":"object","properties":{"id":{"type":"integer"},"order_item_id":{"type":"integer"},"promo_id":{"type":"integer"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount applied"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount amount (cents) or percentage"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","order_item_id","promo_id"]}}}}
```

## The OrderPayment object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"OrderPayment":{"type":"object","properties":{"id":{"type":"integer","description":"Payment ID"},"order_id":{"type":"integer","description":"Associated order ID"},"customer_id":{"type":"integer","nullable":true,"description":"Customer who made the payment (sourced from the parent order; included for convenience so customer-centric reporting doesn't require a second hop through /v2/orders)"},"source_id":{"type":"integer","nullable":true,"description":"Payment source (card) ID (database field)"},"source":{"type":"object","properties":{"id":{"type":"integer","description":"Payment source ID"},"card_id":{"type":"integer","description":"Customer card ID"},"gateway_id":{"type":"integer","description":"Payment gateway ID"},"stripe_source_id":{"type":"string","nullable":true,"description":"Stripe source ID"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"description":"Stripe payment method ID"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"description":"PayPal billing agreement ID"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"stripe_customer_id":{"type":"string","nullable":true,"description":"Stripe customer ID"},"paypal_payer_id":{"type":"string","nullable":true,"description":"PayPal payer ID"},"paypal_customer_id":{"type":"string","nullable":true,"description":"PayPal customer ID"},"paypal_token_id":{"type":"string","nullable":true,"description":"PayPal token ID"},"nmi_customer_vault_id":{"type":"string","nullable":true,"description":"NMI customer vault ID"},"authentication":{"nullable":true,"description":"3D Secure authentication data"},"customer_id":{"type":"integer","description":"Customer ID who owns this source"},"is_active":{"type":"boolean","description":"Whether this source is active"},"is_three_d_secure_supported":{"type":"boolean","description":"Whether 3D Secure is supported"},"type":{"type":"string","nullable":true,"description":"Card brand (visa, mastercard, etc.)"},"last_four":{"type":"string","nullable":true,"description":"Last 4 digits of card number"},"exp_month":{"type":"string","nullable":true,"description":"Expiration month (MM)"},"exp_year":{"type":"string","nullable":true,"description":"Expiration year (YYYY)"},"address_zip":{"type":"string","nullable":true,"description":"Card billing ZIP/postal code"},"country":{"type":"string","nullable":true,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"description":"Card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"description":"Billing city"},"address_state":{"type":"string","nullable":true,"description":"Billing state/province"},"address_country":{"type":"string","nullable":true,"description":"Billing country code"}},"required":["id","card_id","gateway_id","customer_id"],"description":"Payment source (card) object"},"gateway_id":{"type":"integer","nullable":true,"description":"Payment gateway ID"},"initial_payment_id":{"type":"integer","nullable":true,"description":"Initial payment ID (for retries)"},"stripe_charge_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe charge ID"},"stripe_invoice_id":{"type":"string","nullable":true,"description":"Stripe invoice ID"},"stripe_paymentintent_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe PaymentIntent ID"},"paypal_order_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal order ID"},"paypal_capture_id":{"type":"string","nullable":true,"maxLength":255,"description":"PayPal capture ID"},"is_manual":{"type":"boolean","nullable":true,"description":"Whether payment was manually recorded"},"is_3ds_in_progress":{"type":"boolean","description":"Whether 3D Secure authentication is in progress"},"amount":{"type":"integer","description":"Total payment amount in cents"},"amount_paid":{"type":"integer","description":"Amount successfully paid in cents"},"amount_refunded":{"type":"integer","description":"Amount refunded in cents"},"currency":{"type":"string","nullable":true,"enum":["aud","cad","usd","gbp","eur","sgd","aed","afn","all","amd","ang","aoa","ars","awg","azn","bam","bbd","bdt","bgn","bif","bmd","bnd","bob","brl","bsd","bwp","bzd","cdf","chf","clp","cny","cop","crc","cve","czk","djf","dkk","dop","dzd","egp","etb","fjd","fkp","gel","gip","gmd","gnf","gtq","gyd","hkd","hnl","hrk","htg","huf","idr","ils","inr","isk","jmd","jpy","kes","kgs","khr","kmf","krw","kyd","kzt","lak","lbp","lkr","lrd","lsl","mad","mdl","mga","mkd","mmk","mnt","mop","mro","mur","mvr","mwk","mxn","myr","mzn","nad","ngn","nio","nok","npr","nzd","pab","pen","pgk","php","pkr","pln","pyg","qar","ron","rsd","rub","rwf","sar","sbd","scr","sek","shp","sll","sos","srd","std","szl","thb","tjs","top","try","ttd","twd","tzs","uah","ugx","uyu","uzs","vnd","vuv","wst","xaf","xcd","xof","xpf","yer","zar","zmw",null],"description":"Payment currency code"},"failure_reason":{"type":"string","nullable":true,"description":"Human-readable failure reason"},"has_pending_retry":{"type":"boolean","description":"Whether a retry is pending"},"refunded_at":{"type":"string","nullable":true,"format":"date-time","description":"Refund timestamp"},"status":{"type":"string","nullable":true,"enum":["pending","succeeded","failed","refunded","disputed","dispute_refunded",null],"description":"Payment status"},"is_3ds":{"type":"boolean","description":"Whether 3D Secure was used"},"can_skip":{"type":"boolean","description":"Whether payment can be skipped"},"nmi_transaction_id":{"type":"string","nullable":true,"maxLength":255,"description":"NMI transaction ID"},"is_startup_fee":{"type":"boolean","description":"Whether this is a startup/setup fee"},"failure_code":{"type":"string","nullable":true,"maxLength":255,"description":"Gateway-specific failure code"},"payment_method_type":{"type":"string","nullable":true,"maxLength":255,"description":"What actually paid this charge, as the gateway reports it (e.g. card, apple_pay, klarna, afterpay_clearpay). Null when unknown or not recorded — clients should fall back to the card display."},"financing_installments_count":{"type":"integer","nullable":true,"description":"Number of installments for a financing (BNPL) payment. Null for non-financing payments."},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"initial_payment_id":{"type":"integer","nullable":true},"amount":{"type":"integer"},"amount_paid":{"type":"integer"},"amount_refunded":{"type":"integer"},"currency":{"type":"string","nullable":true},"status":{"type":"string"},"failure_reason":{"type":"string","nullable":true},"has_pending_retry":{"type":"boolean","nullable":true},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id"]},"description":"Payment retry attempts"}},"required":["id","order_id","amount_paid"]}}}}
```

## The PaymentSource object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"PaymentSource":{"type":"object","properties":{"id":{"type":"integer","description":"Payment source ID"},"card_id":{"type":"integer","description":"Customer card ID"},"gateway_id":{"type":"integer","description":"Payment gateway ID"},"stripe_source_id":{"type":"string","nullable":true,"description":"Stripe source ID"},"stripe_paymentmethod_id":{"type":"string","nullable":true,"description":"Stripe payment method ID"},"paypal_billing_agreement_id":{"type":"string","nullable":true,"description":"PayPal billing agreement ID"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"stripe_customer_id":{"type":"string","nullable":true,"description":"Stripe customer ID"},"paypal_payer_id":{"type":"string","nullable":true,"description":"PayPal payer ID"},"paypal_customer_id":{"type":"string","nullable":true,"description":"PayPal customer ID"},"paypal_token_id":{"type":"string","nullable":true,"description":"PayPal token ID"},"nmi_customer_vault_id":{"type":"string","nullable":true,"description":"NMI customer vault ID"},"authentication":{"nullable":true,"description":"3D Secure authentication data"},"customer_id":{"type":"integer","description":"Customer ID who owns this source"},"is_active":{"type":"boolean","description":"Whether this source is active"},"is_three_d_secure_supported":{"type":"boolean","description":"Whether 3D Secure is supported"},"type":{"type":"string","nullable":true,"description":"Card brand (visa, mastercard, etc.)"},"last_four":{"type":"string","nullable":true,"description":"Last 4 digits of card number"},"exp_month":{"type":"string","nullable":true,"description":"Expiration month (MM)"},"exp_year":{"type":"string","nullable":true,"description":"Expiration year (YYYY)"},"address_zip":{"type":"string","nullable":true,"description":"Card billing ZIP/postal code"},"country":{"type":"string","nullable":true,"description":"Card country code"},"fingerprint":{"type":"string","nullable":true,"description":"Card fingerprint for duplicate detection"},"cardholder_name_first":{"type":"string","nullable":true,"description":"Cardholder first name"},"cardholder_name_last":{"type":"string","nullable":true,"description":"Cardholder last name"},"address_street1":{"type":"string","nullable":true,"description":"Billing address line 1"},"address_street2":{"type":"string","nullable":true,"description":"Billing address line 2"},"address_city":{"type":"string","nullable":true,"description":"Billing city"},"address_state":{"type":"string","nullable":true,"description":"Billing state/province"},"address_country":{"type":"string","nullable":true,"description":"Billing country code"}},"required":["id","card_id","gateway_id","customer_id"]}}}}
```

## The Subscription object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Subscription":{"type":"object","properties":{"id":{"type":"integer","description":"Subscription ID"},"order_item_id":{"type":"integer","description":"Associated order item ID"},"product_option_price_id":{"type":"integer","description":"Product option price ID"},"card_id":{"type":"integer","description":"Payment card ID"},"swapped_from_id":{"type":"integer","nullable":true,"description":"Previous subscription ID if swapped"},"published_block_item_id":{"type":"integer","nullable":true,"description":"Published block item ID"},"replace_published_block_item_id":{"type":"integer","nullable":true,"description":"Replacement block item ID"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Subscription name/description"},"block_type":{"type":"string","nullable":true,"maxLength":255,"description":"Block type identifier"},"stripe_subscription_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription ID"},"stripe_subscription_item_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription item ID"},"status":{"type":"string","enum":["pending","trialing","active","past_due","canceling","canceled","unpaid","swapped"],"description":"Subscription status"},"next_payment_at":{"type":"string","nullable":true,"format":"date-time","description":"Next scheduled payment date"},"trial_days":{"type":"integer","description":"Trial period duration in days"},"num_payment_skips_remaining":{"type":"integer","description":"Number of payment skips remaining"},"tax_rate":{"type":"number","nullable":true,"description":"Tax rate as decimal"},"is_commissionable":{"type":"boolean","nullable":true,"description":"Whether subscription generates affiliate commission"},"is_trial_end_upcoming_sent":{"type":"boolean","nullable":true,"description":"Whether trial end notification was sent"},"unpaid_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription became unpaid"},"canceled_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription was canceled"},"order_id":{"type":"integer","nullable":true,"description":"Associated order ID"},"tax_type":{"type":"string","nullable":true,"description":"Type of tax (vat, tax, gst)"},"replace_price_id":{"type":"integer","nullable":true,"description":"Replacement price ID"},"published_checkout_item_id":{"type":"string","nullable":true,"maxLength":255,"description":"Published checkout item ID"},"event_ready_at":{"type":"string","nullable":true,"format":"date-time","description":"When subscription event was ready"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Array of payment IDs (excluding initial payment)"},"retry_schedule":{"type":"array","items":{"type":"string"},"description":"Pending retry schedule for past_due subscriptions (array of date strings)"},"current_payment_status":{"type":"string","nullable":true,"description":"Status of most recent payment"},"detail":{"type":"object","additionalProperties":{"nullable":true},"description":"Calculated subscription details (pricing, totals)"},"discounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Discount ID"},"subscription_id":{"type":"integer","description":"Associated subscription ID"},"promo_id":{"type":"integer","description":"Promotion ID"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"stripe_coupon_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe coupon ID"},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount (fixed amount or percentage)"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount value (cents for amount, percentage for percent)"},"duration_in_months":{"type":"integer","description":"Duration of discount in months"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"deactivated_at":{"type":"string","nullable":true,"format":"date-time","description":"When the discount was deactivated"},"promo_code":{"type":"string","nullable":true,"description":"Promo code from related promo"}},"required":["id","subscription_id","promo_id"]},"description":"Discounts applied to subscription"},"usage":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Usage data from payment gateway"},"payments":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Subscription payments (expansion: payments)"},"custom_fields":{"type":"array","items":{"nullable":true},"description":"Custom fields (expansion: custom_fields)"},"customer":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Customer data (expansion: customer)"},"order":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Order data (expansion: order)"},"price":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Product option price with nested option and product"},"card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment card associated with this subscription"},"gateway":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment gateway used for this subscription"}},"required":["id","order_item_id","product_option_price_id","card_id"]}}}}
```

## The SubscriptionDiscount object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"SubscriptionDiscount":{"type":"object","properties":{"id":{"type":"integer","description":"Discount ID"},"subscription_id":{"type":"integer","description":"Associated subscription ID"},"promo_id":{"type":"integer","description":"Promotion ID"},"promo_code_id":{"type":"integer","nullable":true,"description":"Issued code redeemed by this discount, when the promotion is unique-mode."},"stripe_coupon_id":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe coupon ID"},"discount_type":{"type":"string","nullable":true,"enum":["amount","percent",null],"description":"Type of discount (fixed amount or percentage)"},"discount_offset":{"type":"integer","nullable":true,"description":"Discount value (cents for amount, percentage for percent)"},"duration_in_months":{"type":"integer","description":"Duration of discount in months"},"use_taxes":{"type":"boolean","nullable":true,"description":"Which subtotal tax is calculated on: true = the discounted subtotal, false = the full, undiscounted subtotal (NULL behaves as false)"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"deactivated_at":{"type":"string","nullable":true,"format":"date-time","description":"When the discount was deactivated"}},"required":["id","subscription_id","promo_id"]}}}}
```

## The Paymentplan object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"Paymentplan":{"type":"object","properties":{"id":{"type":"integer","description":"Payment plan ID"},"order_id":{"type":"integer","description":"Associated order ID"},"card_id":{"type":"integer","description":"Card used for payments"},"status":{"type":"string","enum":["active","past_due","unpaid","completed","defaulted"],"description":"Payment plan status. 'defaulted' is a terminal write-off state set via the pay endpoint with payoff_outcome='defaulted'."},"next_payment_at":{"type":"string","nullable":true,"format":"date-time","description":"Next scheduled payment date"},"finished_at":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp when the plan reached a terminal state (completed or defaulted). Null for active plans."},"frequency":{"type":"string","enum":["day","week","month","year"],"description":"Payment frequency"},"frequency_count":{"type":"integer","description":"Frequency multiplier (e.g., 2 for bi-weekly)"},"is_finance_hidden":{"type":"boolean","nullable":true,"description":"Whether finance details are hidden"},"unpaid_at":{"type":"string","nullable":true,"format":"date-time","description":"When payment plan became unpaid"},"is_scheduled":{"type":"boolean","description":"Whether plan is scheduled"},"created_at":{"type":"string","nullable":true,"format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","nullable":true,"format":"date-time","description":"Last update timestamp"},"remaining_balance":{"type":"integer","description":"Remaining balance in cents"},"paid_amount":{"type":"integer","description":"Total paid amount in cents"},"total_amount":{"type":"integer","description":"Total plan amount in cents"},"defaulted_amount":{"type":"integer","description":"Magnitude of write-off adjustments tied to this plan from a payoff_outcome='defaulted' request, in cents (positive). Zero for plans that were never defaulted."},"payments_made":{"type":"integer","description":"Number of payments made"},"payments_remaining":{"type":"integer","description":"Number of payments remaining"},"item_ids":{"type":"array","items":{"type":"integer"},"description":"Order item IDs in this plan"},"current_payment_status":{"type":"string","nullable":true,"description":"Status of most recent payment"},"payment_ids":{"type":"array","items":{"type":"integer"},"description":"Payment IDs for this plan"},"retry_schedule":{"type":"array","items":{"type":"string"},"description":"Pending retry schedule for past_due plans (array of date strings)"},"detail":{"type":"object","additionalProperties":{"nullable":true},"description":"Calculated payment plan details"},"items":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Payment plan items (expansion: items)"},"payments":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Payments for this plan (expansion: payments)"},"order":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Order data (expansion: order)"},"customer":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Customer data (expansion: customer)"},"custom_fields":{"type":"array","items":{"nullable":true},"description":"Custom fields (expansion: custom_fields)"},"card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment card (expansion: card)"},"gateway":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Payment gateway info (expansion: gateway)"}},"required":["id","order_id","card_id","status","frequency"]}}}}
```

## The AnalyticsQueryResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"AnalyticsQueryResponse":{"type":"object","properties":{"groupBy":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"comparison":{"type":"object","nullable":true,"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"meta":{"type":"string"},"metrics":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"}},"required":["value"]}}},"required":["key","label","metrics"]}},"totals":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"}},"required":["value"]}}},"required":["groupBy","period","comparison","groups","totals"]}}}}
```

## The AnalyticsQueryRequest object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"AnalyticsQueryRequest":{"type":"object","properties":{"object":{"type":"string","enum":["account","checkout","product"],"description":"Query scope: 'account' for account-wide analytics, or 'checkout' to scope to a single checkout (requires objId). 'product' is not yet supported."},"objId":{"type":"string","description":"Id of the scoped object. Required when object is 'checkout'; omit for 'account'."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric keys to return (e.g. ['revenue', 'mrr', 'refunds']). Omit for the default orders-family set. See get_analytics_capabilities for all keys and their groupBy compatibility."},"groupBy":{"type":"string","description":"'interval' for a time series, or a dimension key (channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, referring_domain) for an attribution breakdown — see get_analytics_capabilities."},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"description":"Primary date range. start/end are UTC ISO 8601 strings (e.g. '2026-06-01T00:00:00Z'); timezone offsets are not interpreted."},"compare":{"anyOf":[{"type":"string","enum":["previous_period"]},{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},{"nullable":true}],"description":"Optional comparison window: 'previous_period' for the automatically-derived preceding window of equal length, or a custom {start, end} object (UTC ISO 8601). Adds a `previous` value to every metric cell."},"grouping":{"type":"string","enum":["day","week","month"],"description":"Bucket size when groupBy is 'interval'. Defaults to 'day'."},"touch":{"type":"string","enum":["first","last"],"description":"Attribution touch for dimension breakdowns: 'last' (default) groups by the last-touch snapshot, 'first' by the first-touch snapshot. Ignored for groupBy 'interval'; conversion_rate is visit-grain and unaffected."}},"required":["object","groupBy","period"]}}}}
```

## The AnalyticsCapabilitiesResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"AnalyticsCapabilitiesResponse":{"type":"object","properties":{"objects":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"format":{"type":"string"},"family":{"type":"string"},"kind":{"type":"string"},"description":{"type":"string"},"group_by":{"type":"array","items":{"type":"string"}},"anchor":{"type":"string"}},"required":["key","label","format","family","kind","description","group_by"]}},"dimensions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"]}},"intervals":{"type":"array","items":{"type":"string"}},"compare":{"type":"array","items":{"type":"string"}}},"required":["objects","metrics","dimensions","intervals","compare"]}}}}
```

## The WebhookEndpointCreate object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"WebhookEndpointCreate":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"URL to receive webhook events"},"description":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable description of the webhook"},"events":{"type":"array","items":{"type":"string"},"description":"List of event types to subscribe to, defaults to ['*']. Names are colon-delimited and must match the catalog exactly; GET /v2/webhook-event-types lists every supported name. An unknown name is rejected."}},"required":["url"]}}}}
```

## The WebhookEndpointUpdate object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"URL to receive webhook events"},"description":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable description of the webhook"},"events":{"type":"array","items":{"type":"string"},"description":"List of event types to subscribe to. Names are colon-delimited and must match the catalog exactly; GET /v2/webhook-event-types lists every supported name. An unknown name is rejected."},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status (active or inactive)"}}}}}}
```

## The ReportTypeV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportTypeV2":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"data_type":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"nullable":true},"label":{"type":"string"}},"required":["label"]}}},"required":["name","data_type"]}},"datasets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"display_type":{"type":"string"},"grouping_properties":{"type":"array","items":{"type":"string"}},"grouping_intervals":{"type":"object","additionalProperties":{"type":"string"}},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["name","label","data_type"]}}},"required":["type","display_type","grouping_properties","columns"]}},"relative_dates":{"type":"array","items":{"type":"string"}},"layout":{"type":"array","items":{"$ref":"#/components/schemas/ReportLayoutSection"}}},"required":["type","label","filters","datasets","relative_dates","layout"]},"ReportLayoutSection":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["stats"]},"group":{"type":"string"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["chart"]},"shape":{"type":"string","enum":["time_series","breakdown","single"]},"source":{"type":"string","enum":["interval","dataset"]},"x":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string","enum":["currency","number","percentage"]}},"required":["key","label","data_type"]},"minItems":1}},"required":["kind","shape","source","x","series"]},{"type":"object","properties":{"kind":{"type":"string","enum":["dataset"]},"dataset":{"type":"string"}},"required":["kind","dataset"]}]}}}}
```

## The ReportLayoutSection object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportLayoutSection":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["stats"]},"group":{"type":"string"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["chart"]},"shape":{"type":"string","enum":["time_series","breakdown","single"]},"source":{"type":"string","enum":["interval","dataset"]},"x":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string","enum":["currency","number","percentage"]}},"required":["key","label","data_type"]},"minItems":1}},"required":["kind","shape","source","x","series"]},{"type":"object","properties":{"kind":{"type":"string","enum":["dataset"]},"dataset":{"type":"string"}},"required":["kind","dataset"]}]}}}}
```

## The ReportV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportV2":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","description":"Report type key, e.g. 'product_sales'. See GET /v2/reports/types."},"name":{"type":"string","nullable":true},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string","description":"IANA timezone the report buckets dates in (legacy semantics — unlike /v2/analytics, which is UTC-only)."},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset resolved per run, e.g. 'Last Month'."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null]},"frequency_count":{"type":"integer","nullable":true},"next_run_at":{"type":"string","nullable":true,"format":"date-time"},"is_active":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"required":["user_id"]},"description":"Scheduled-report recipients (account users with report access)."},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","name","filters","timezone","relative_date","frequency","frequency_count","next_run_at","is_active","created_at","updated_at"]}}}}
```

## The ReportV2Create object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportV2Create":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","nullable":true,"maxLength":255},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string"},"relative_date":{"type":"string"},"frequency":{"type":"string","enum":["day","week","month","year"]},"frequency_count":{"type":"integer","minimum":0,"exclusiveMinimum":true},"users":{"type":"array","items":{"$ref":"#/components/schemas/ReportRecipientV2"},"description":"Schedule recipients — {user_id} or {email} each. When scheduling (frequency set) and this is omitted, defaults to the authorizing user."}},"required":["type"]},"ReportRecipientV2":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"}},"description":"Exactly one of user_id or email. Omitting users entirely while scheduling defaults the recipient to the authorizing user."}}}}
```

## The ReportRecipientV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportRecipientV2":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"}},"description":"Exactly one of user_id or email. Omitting users entirely while scheduling defaults the recipient to the authorizing user."}}}}
```

## The ReportV2Update object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportV2Update":{"type":"object","properties":{"name":{"type":"string","nullable":true,"maxLength":255,"description":"Report name. null clears the name."},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string"},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset, e.g. 'Last Month'. null clears the schedule window (only valid when frequency is also null/cleared)."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null],"description":"Schedule frequency. null clears the schedule (next_run_at becomes null)."},"frequency_count":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"description":"Schedule interval multiplier. null clears it (treated as 1 while frequency is set)."},"users":{"type":"array","items":{"$ref":"#/components/schemas/ReportRecipientV2"},"description":"Replaces the recipient list — {user_id} or {email} each; [] clears it."},"is_active":{"type":"boolean","description":"true reactivates a soft-deleted report; false soft-deletes (same as DELETE)."}}},"ReportRecipientV2":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"}},"description":"Exactly one of user_id or email. Omitting users entirely while scheduling defaults the recipient to the authorizing user."}}}}
```

## The ReportRunV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportRunV2":{"type":"object","properties":{"id":{"type":"integer"},"report_id":{"type":"integer"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"start_at":{"type":"string","nullable":true,"format":"date-time"},"end_at":{"type":"string","nullable":true,"format":"date-time"},"started_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"error_reason":{"type":"string","nullable":true},"stats":{"type":"object","nullable":true,"properties":{"flat_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["value","label","data_type"]}}},"description":"Present on a completed run: the summary stat block (small, conversationally useful). null when the run computed no stats OR its stored data has expired — check data_expired."},"data_expired":{"type":"boolean","description":"Present on a completed run. true means the run's stored result data has been deleted (retained ~1 year), so stats is null and results return zero rows. Re-run the report rather than reading it as zero activity — but note a new run uses the report's current settings, so a relative date range covers the period ending now rather than this run's dates."},"created_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","report_id","status","start_at","end_at","started_at","completed_at","error_reason","created_at"]}}}}
```

## The ReportRunResultsV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportRunResultsV2":{"type":"object","properties":{"dataset":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["name","label","data_type"]}},"rows":{"type":"array","items":{"type":"array","items":{"nullable":true}}}},"required":["dataset","columns","rows"]}}}}
```

## The ReportExportV2 object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"ReportExportV2":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed download URL for the full CSV. No authentication needed; expires quickly."},"expires_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["url","expires_at"]}}}}
```

## The V1ListResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"V1ListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true},"description":"Array of resource objects"},"page":{"type":"integer","description":"Current page number"},"per_page":{"type":"integer","description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"total_pages":{"type":"integer","description":"Total number of pages"}},"required":["data","page","per_page","total","total_pages"]}}}}
```

## The V1ErrorResponse object

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"components":{"schemas":{"V1ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error","error_description"]}}}}
```
