> 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/subscriptions.md).

# Subscriptions

Subscription management

## List subscriptions

> Retrieve a paginated list of subscriptions

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"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"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions":{"get":{"tags":["subscriptions"],"summary":"List subscriptions","description":"Retrieve a paginated list of subscriptions","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Items per page (max 100)"},"required":false,"description":"Items per page (max 100)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of expansions: payments, usage, custom_fields, customer, order"},"required":false,"description":"Comma-separated list of expansions: payments, usage, custom_fields, customer, order","name":"include","in":"query"},{"schema":{"type":"string","description":"Filter by id (exact match)."},"required":false,"description":"Filter by id (exact match).","name":"filter[id]","in":"query"},{"schema":{"type":"string","description":"Filter by id (greater than or equal)"},"required":false,"description":"Filter by id (greater than or equal)","name":"filter[id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by id (less than or equal)"},"required":false,"description":"Filter by id (less than or equal)","name":"filter[id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by id (excluding a comma-separated list)"},"required":false,"description":"Filter by id (excluding a comma-separated list)","name":"filter[id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by status (exact match). Valid values: pending, trialing, active, past_due, canceling, canceled, unpaid, swapped."},"required":false,"description":"Filter by status (exact match). Valid values: pending, trialing, active, past_due, canceling, canceled, unpaid, swapped.","name":"filter[status]","in":"query"},{"schema":{"type":"string","description":"Filter by status (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by status (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[status.in]","in":"query"},{"schema":{"type":"string","description":"Filter by status (excluding a comma-separated list)"},"required":false,"description":"Filter by status (excluding a comma-separated list)","name":"filter[status.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (exact match)."},"required":false,"description":"Filter by order_id (exact match).","name":"filter[order_id]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (greater than or equal)"},"required":false,"description":"Filter by order_id (greater than or equal)","name":"filter[order_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (less than or equal)"},"required":false,"description":"Filter by order_id (less than or equal)","name":"filter[order_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by order_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[order_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by order_id (excluding a comma-separated list)"},"required":false,"description":"Filter by order_id (excluding a comma-separated list)","name":"filter[order_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (exact match)."},"required":false,"description":"Filter by customer_id (exact match).","name":"filter[customer_id]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (greater than or equal)"},"required":false,"description":"Filter by customer_id (greater than or equal)","name":"filter[customer_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (less than or equal)"},"required":false,"description":"Filter by customer_id (less than or equal)","name":"filter[customer_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by customer_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[customer_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by customer_id (excluding a comma-separated list)"},"required":false,"description":"Filter by customer_id (excluding a comma-separated list)","name":"filter[customer_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by email (exact match)."},"required":false,"description":"Filter by email (exact match).","name":"filter[email]","in":"query"},{"schema":{"type":"string","description":"Filter by email (contains)"},"required":false,"description":"Filter by email (contains)","name":"filter[email.contains]","in":"query"},{"schema":{"type":"string","description":"Filter by product_id (exact match)."},"required":false,"description":"Filter by product_id (exact match).","name":"filter[product_id]","in":"query"},{"schema":{"type":"string","description":"Filter by product_id (greater than or equal)"},"required":false,"description":"Filter by product_id (greater than or equal)","name":"filter[product_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by product_id (less than or equal)"},"required":false,"description":"Filter by product_id (less than or equal)","name":"filter[product_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by product_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by product_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[product_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by product_id (excluding a comma-separated list)"},"required":false,"description":"Filter by product_id (excluding a comma-separated list)","name":"filter[product_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by product_option_price_id (exact match)."},"required":false,"description":"Filter by product_option_price_id (exact match).","name":"filter[product_option_price_id]","in":"query"},{"schema":{"type":"string","description":"Filter by product_option_price_id (greater than or equal)"},"required":false,"description":"Filter by product_option_price_id (greater than or equal)","name":"filter[product_option_price_id.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by product_option_price_id (less than or equal)"},"required":false,"description":"Filter by product_option_price_id (less than or equal)","name":"filter[product_option_price_id.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by product_option_price_id (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by product_option_price_id (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[product_option_price_id.in]","in":"query"},{"schema":{"type":"string","description":"Filter by product_option_price_id (excluding a comma-separated list)"},"required":false,"description":"Filter by product_option_price_id (excluding a comma-separated list)","name":"filter[product_option_price_id.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (exact match)."},"required":false,"description":"Filter by created_at (exact match).","name":"filter[created_at]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (greater than or equal)"},"required":false,"description":"Filter by created_at (greater than or equal)","name":"filter[created_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (less than or equal)"},"required":false,"description":"Filter by created_at (less than or equal)","name":"filter[created_at.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (exact match)."},"required":false,"description":"Filter by updated_at (exact match).","name":"filter[updated_at]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (greater than or equal)"},"required":false,"description":"Filter by updated_at (greater than or equal)","name":"filter[updated_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by updated_at (less than or equal)"},"required":false,"description":"Filter by updated_at (less than or equal)","name":"filter[updated_at.lte]","in":"query"},{"schema":{"type":"string","description":"Filter by next_payment_at (exact match)."},"required":false,"description":"Filter by next_payment_at (exact match).","name":"filter[next_payment_at]","in":"query"},{"schema":{"type":"string","description":"Filter by next_payment_at (greater than or equal)"},"required":false,"description":"Filter by next_payment_at (greater than or equal)","name":"filter[next_payment_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by next_payment_at (less than or equal)"},"required":false,"description":"Filter by next_payment_at (less than or equal)","name":"filter[next_payment_at.lte]","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"}],"responses":{"200":{"description":"Successful response with paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Current page number"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["page","limit","total","pages"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retrieve a subscription

> Retrieve a single subscriptions by ID

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"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"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}":{"get":{"tags":["subscriptions"],"summary":"Retrieve a subscription","description":"Retrieve a single subscriptions by ID","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"subscriptions ID"},"required":true,"description":"subscriptions ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of expansions: payments, usage, custom_fields, customer, order"},"required":false,"description":"Comma-separated list of expansions: payments, usage, custom_fields, customer, order","name":"include","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Preview proration for a plan change

> Suggested first payment for swapping this subscription onto a different price, based on the unused remainder of the current billing period. Read-only.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/price/{price_id}/proration":{"get":{"tags":["subscriptions"],"summary":"Preview proration for a plan change","description":"Suggested first payment for swapping this subscription onto a different price, based on the unused remainder of the current billing period. Read-only.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"},{"schema":{"type":"string","description":"New Price ID"},"required":true,"description":"New Price ID","name":"price_id","in":"path"},{"schema":{"type":"string","description":{"def":{"type":"optional","innerType":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null}},"type":"optional"}},"required":false,"description":{"def":{"type":"optional","innerType":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null}},"type":"optional"},"name":"with_discount","in":"query"},{"schema":{"type":"string","description":{"def":{"type":"optional","innerType":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null}},"type":"optional"}},"required":false,"description":{"def":{"type":"optional","innerType":{"def":{"type":"string"},"type":"string","format":null,"minLength":null,"maxLength":null}},"type":"optional"},"name":"do_recalculate_taxes","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Change subscription price

> Swap a subscription to a different price/plan. Optionally charge or refund the balance difference, or set the new plan's first payment directly.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/price/{price_id}":{"put":{"tags":["subscriptions"],"summary":"Change subscription price","description":"Swap a subscription to a different price/plan. Optionally charge or refund the balance difference, or set the new plan's first payment directly.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"},{"schema":{"type":"string","description":"New Price ID"},"required":true,"description":"New Price ID","name":"price_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_changed_immediately":{"type":"boolean","description":"Whether to bill immediately or at next cycle"},"subscription_start_at":{"type":"string","description":"Future start date for the new subscription"},"balance_impact_type":{"type":"string","enum":["charge","refund","prorate"],"description":"`charge` and `refund` are one-time adjustments made alongside the swap, on top of whatever the new plan bills. `prorate` instead REPLACES the new plan's first payment with `balance_impact_amount`, leaving the next payment a full cycle away; it requires `is_changed_immediately` and is not available with `subscription_start_at`. Use GET /v2/subscriptions/{id}/price/{price_id}/proration for a suggested amount."},"balance_impact_amount":{"type":"integer","minimum":0,"description":"Amount in the smallest currency unit ($10.00 USD = 1000; ¥1500 JPY = 1500). For `charge` and `refund` this is the adjustment and must be positive. For `prorate` it is the new plan's first payment: 0 is allowed (collect nothing now) and it may not exceed what the new plan's first payment would otherwise have been."},"with_discount":{"type":"boolean","description":"Pull forward existing discount to new subscription"},"do_recalculate_taxes":{"type":"boolean","description":"Recalculate taxes based on current addresses"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Add notes to subscription

> Add a note to a subscription, saved as an event.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/notes":{"post":{"tags":["subscriptions"],"summary":"Add notes to subscription","description":"Add a note to a subscription, saved as an event.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Notes to add"}},"required":["notes"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Cancel a subscription

> Cancel a subscription. Can cancel immediately or at the end of the current billing period.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/cancel":{"put":{"tags":["subscriptions"],"summary":"Cancel a subscription","description":"Cancel a subscription. Can cancel immediately or at the end of the current billing period.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_canceled_immediately":{"type":"boolean","description":"Cancel immediately (true) or at end of billing period (false)"},"skip_integration_actions":{"type":"boolean","description":"Skip triggering integration cancellation actions"},"notes":{"type":"string","description":"Internal notes for the cancellation"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Uncancel a subscription

> Reverse a pending cancellation and reactivate the subscription.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/uncancel":{"put":{"tags":["subscriptions"],"summary":"Uncancel a subscription","description":"Reverse a pending cancellation and reactivate the subscription.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Add a new card to subscription

> Create a new payment method and assign it to the subscription.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/card":{"post":{"tags":["subscriptions"],"summary":"Add a new card to subscription","description":"Create a new payment method and assign it to the subscription.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"nullable":true,"description":"Payment gateway token (e.g. Stripe payment method, PayPal token)"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Update subscription card

> Update a subscription to use an existing card on file.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/card":{"put":{"tags":["subscriptions"],"summary":"Update subscription card","description":"Update a subscription to use an existing card on file.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"number","description":"ID of the existing card to use"}},"required":["card_id"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Update the next billing date of a subscription

> Update the next billing date for a subscription. Must be in the future. Refused for canceled, swapped or pending subscriptions (resume it first), and for a Stripe-gateway subscription with no Stripe subscription behind it. For a Stripe subscription the date must also be within 730 days (Stripe's trial\_end ceiling). A past\_due or unpaid subscription is reactivated by the new date; any other status is left as it is.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/nextbillingdate":{"put":{"tags":["subscriptions"],"summary":"Update the next billing date of a subscription","description":"Update the next billing date for a subscription. Must be in the future. Refused for canceled, swapped or pending subscriptions (resume it first), and for a Stripe-gateway subscription with no Stripe subscription behind it. For a Stripe subscription the date must also be within 730 days (Stripe's trial_end ceiling). A past_due or unpaid subscription is reactivated by the new date; any other status is left as it is.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"next_payment_at":{"type":"string","description":"New next billing date (ISO 8601)"},"notes":{"type":"string"}},"required":["next_payment_at"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Hard resume a subscription

> Resume a canceled or unpaid subscription by creating a new subscription at the same price.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/hardresume":{"put":{"tags":["subscriptions"],"summary":"Hard resume a subscription","description":"Resume a canceled or unpaid subscription by creating a new subscription at the same price.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_start_at":{"type":"string","description":"Future start date"},"with_discount":{"type":"boolean","description":"Pull forward existing discount"},"do_recalculate_taxes":{"type":"boolean","description":"Recalculate taxes"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Process early renewal

> Charge the subscription immediately and extend the billing period. Refused, before anything is charged, when the resulting next payment date would be more than 730 days out — Stripe will not accept a trial\_end that far ahead, so a subscription renewed a full cycle early (an annual plan across a leap day, or any two-year plan) has to wait until closer to its current billing date.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/earlyrenewal":{"put":{"tags":["subscriptions"],"summary":"Process early renewal","description":"Charge the subscription immediately and extend the billing period. Refused, before anything is charged, when the resulting next payment date would be more than 730 days out — Stripe will not accept a trial_end that far ahead, so a subscription renewed a full cycle early (an annual plan across a leap day, or any two-year plan) has to wait until closer to its current billing date.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"do_recalculate_taxes":{"type":"boolean","description":"Recalculate taxes"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Make a manual payment

> Process a manual one-time payment on a subscription.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/payment":{"post":{"tags":["subscriptions"],"summary":"Make a manual payment","description":"Process a manual one-time payment on a subscription.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Payment amount in the smallest currency unit ($10.00 USD = 1000; ¥1500 JPY = 1500)."},"notes":{"type":"string"}},"required":["amount"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Apply a discount

> Apply a promo code discount to a subscription. Replaces any existing discount.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/discount":{"put":{"tags":["subscriptions"],"summary":"Apply a discount","description":"Apply a promo code discount to a subscription. Replaces any existing discount.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"promo_id":{"type":"number","description":"ID of the promo code to apply"},"notes":{"type":"string"}},"required":["promo_id"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Remove discount

> Remove the active discount from a subscription.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"subscriptions","description":"Subscription management"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["subscriptions"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/subscriptions/{id}/discount":{"delete":{"tags":["subscriptions"],"summary":"Remove discount","description":"Remove the active discount from a subscription.","parameters":[{"schema":{"type":"string","description":"Subscription ID"},"required":true,"description":"Subscription ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```
