{ "openapi": "3.1.0", "servers": [ { "url": "https://{defaultHost}", "variables": { "defaultHost": { "default": "api.surecart.com" } } } ], "security": [ { "bearer_auth": [] } ], "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "abandoned_checkout_body": { "properties": { "notifications_enabled": { "type": "boolean", "description": "Whether or not notifications should be sent to the customer for this abandoned checkout." } } }, "abandoned_checkout_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/abandoned_checkout_body" }, { "properties": { "notification_status": { "type": "string", "description": "The current notification status for this abandonded checkout, which can be one of `not_scheduled`, `scheduled`, or `sent`." }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this abandoned checkout's correct portal page (hosted or external)." }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "promotion": { "nullable": true, "anyOf": [ { "type": "string", "description": "The promotion that was auto-generated for this abandoned checkout.\n\n[Expandable](/api-reference/expanding-responses) – The associated promotion ID." }, { "$ref": "#/components/schemas/promotion_response", "description": "The promotion that was auto-generated for this abandoned checkout.\n\n[Expanded](/api-reference/expanding-responses) – The associated promotion object." } ] }, "recovered_at": { "type": "integer", "nullable": true, "description": "If the abandoned checkout has been recovered, the time it was recovered at." }, "recovered_checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "The checkout that was recovered from this abandoned checkout.\n\n[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "The checkout that was recovered from this abandoned checkout.\n\n[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "abandoned_checkout_protocol_body": { "properties": { "enabled": { "type": "boolean", "description": "If set to `true` abandonded checkout reminder emails will be sent to customers." }, "first_promotion_notification": { "type": "integer", "nullable": true, "description": "The first notification that should have an auto-generated promotion code – can be one of `1`, `2`, `3` or `null`. For example, if set to `2` the promotion code will be generated when the second notification is sent. If `null` a promotion code will never be generated." }, "grace_period_days": { "type": "integer", "description": "The number of days to wait after a customer's purchase before allowing an abandoned checkout to be created. This helps to prevent abandoned checkouts being created for customers very soon after they have made a purchase." }, "ignore_purchased_products": { "type": "boolean", "description": "Whether or not to ignore checkouts where the customer has already purchased all of the products in the checkout." }, "notification_delays": { "type": "array", "description": "The timing schedule for abandoned checkout notifications. It is an array of integers representing the delay in seconds for all notifications. For example, a value of `[3600, 86400, 432000]` indicates that notifications will be sent 1 hour, 24 hours, and 5 days after a checkout is abandoned. The number of notifications (items in array) must be between 1 and 3." }, "promotion_expires_after_days": { "type": "integer", "nullable": true, "description": "The number of days that the auto-generated promotion code should be valid for. If set to 'null' it is valid forever." }, "test_mode_enabled": { "type": "boolean", "description": "Whether or not abandoned checkouts should be created for test mode checkouts." } } }, "abandoned_checkout_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/abandoned_checkout_protocol_body" }, { "properties": { "coupon": { "anyOf": [ { "type": "string", "description": "The coupon that is used when creating discounts for abandoned checkouts.\n\n[Expandable](/api-reference/expanding-responses) – The associated coupon ID." }, { "$ref": "#/components/schemas/coupon_response", "description": "The coupon that is used when creating discounts for abandoned checkouts.\n\n[Expanded](/api-reference/expanding-responses) – The associated coupon object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "account_base": { "properties": { "currency": { "type": "string", "description": "The default currency for this account. This will be used as the default value for `Price`, `Checkout`, and other objects that have the `currency` attribute." }, "name": { "type": "string", "description": "The full name, business name, or other short descriptor for this account." }, "locale": { "type": "string", "description": "The language that will be used for all customer notifications, invoices, etc. Current available locales are `en`, `bg`, `de`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `pt_br`." }, "time_zone": { "type": "string", "description": "The time zone of the account. Values must be a valid IANA time zone database identifier." }, "url": { "type": "string", "nullable": true, "description": "The URL of this account's store. This will be used as the base for all redirects back to your store." } } }, "account_body": { "allOf": [ { "$ref": "#/components/schemas/account_base" } ] }, "account_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/account_base" }, { "properties": { "abandoned_checkout_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated abandoned checkout protocol ID." }, { "$ref": "#/components/schemas/abandoned_checkout_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated abandoned checkout protocol object." } ] }, "affililiation_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affililiation protocol ID." }, { "$ref": "#/components/schemas/affililiation_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affililiation protocol object." } ] }, "brand": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated brand ID." }, { "$ref": "#/components/schemas/brand_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated brand object." } ] }, "cache_keys": { "type": "object", "description": "A collection of cache keys for various resource collections on this account. These values can be used to invalidate your local cache for each resource collection." }, "claimed": { "type": "boolean", "description": "Whether or not this account has been claimed yet." }, "claim_url": { "type": "string", "nullable": true, "description": "If not claimed, the URL where this account can be claimed." }, "claim_window_ends_at": { "type": "integer", "nullable": true, "description": "If not claimed, the time at which the claim window for this account ends. Measured in seconds since the Unix epoch." }, "currency_locked": { "type": "boolean", "description": "Whether or not the currency is locked for this account. The currency is locked once the first live order is created." }, "checkout_portal_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout portal protocol ID." }, { "$ref": "#/components/schemas/checkout_portal_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout portal protocol object." } ] }, "customer_notification_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer notification protocol ID." }, { "$ref": "#/components/schemas/customer_notification_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer notification protocol object." } ] }, "customer_portal_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer portal protocol ID." }, { "$ref": "#/components/schemas/customer_portal_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer portal protocol object." } ] }, "entitlements": { "type": "object", "description": "The specific features that this account is entitled to." }, "medias_total_byte_size": { "type": "integer", "description": "The total number of bytes from this account's medias." }, "plan": { "type": "object", "description": "Details of the current plan this account is on." }, "public_token": { "type": "string", "description": "The public API token for this account." }, "review_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated review protocol ID." }, { "$ref": "#/components/schemas/review_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated review protocol object." } ] }, "shipping_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping protocol ID." }, { "$ref": "#/components/schemas/shipping_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping protocol object." } ] }, "subscription_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated subscription protocol ID." }, { "$ref": "#/components/schemas/subscription_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated subscription protocol object." } ] }, "tax_protocol": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax protocol ID." }, { "$ref": "#/components/schemas/tax_protocol_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax protocol object." } ] }, "seeded_at": { "type": "integer", "nullable": true, "description": "Time when the account was seeded." }, "test_data_purged_at": { "type": "integer", "nullable": true, "description": "Time at which the test data was last purged." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "activation_base": { "properties": { "fingerprint": { "type": "string", "description": "The identifier for this activation. For example a URL, a machine fingerprint, etc." }, "name": { "type": "string", "nullable": true, "description": "The name of this activation." } } }, "activation_body": { "allOf": [ { "$ref": "#/components/schemas/activation_base" }, { "properties": { "license": { "type": "string", "description": "The UUID of the license." } } } ] }, "activation_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/activation_base" }, { "properties": { "counted": { "type": "boolean", "description": "Whether or not this activation counts towards the activation limit." }, "license": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated license ID." }, { "$ref": "#/components/schemas/license_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated license object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "address_body": { "properties": { "city": { "type": "string", "description": "City, district, suburb, town, or village." }, "country": { "type": "string", "description": "The two-letter code of the country - ISO 3166-1. (Reference the Atlas API for all available codes.)" }, "line_1": { "type": "string", "description": "Address line 1 (e.g., street, PO Box, or company name)." }, "line_2": { "type": "string", "nullable": true, "description": "Address line 2 (e.g., apartment, suite, unit, or building)." }, "name": { "type": "string", "description": "The full name or business name for this address. (If empty, this will fallback to the customer's name.)" }, "postal_code": { "type": "string", "description": "ZIP or postal code." }, "state": { "type": "string", "description": "The code of the state - ISO 3166-2. (Reference the Atlas API for all available codes.)" } } }, "address_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/address_body" }, { "properties": { "formatted_string": { "type": "string", "description": "A formatted string representation of the address." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "affiliation_body": { "allOf": [ { "properties": { "bio": { "type": "string", "description": "A short blurb from this affiliate describing how they will promote this store." }, "code": { "type": "string", "description": "The affiliate's unique code." }, "commission_structure": { "description": "The commission structure to use when calculating referral commissions for this specific affiliation.", "allOf": [ { "$ref": "#/components/schemas/commission_structure_base" } ] }, "email": { "type": "string", "description": "The affiliate's email address." }, "first_name": { "type": "string", "description": "The affiliate's first name." }, "last_name": { "type": "string", "nullable": true, "description": "The affiliate's last name." }, "payout_email": { "type": "string", "nullable": true, "description": "The affiliate's payout email address." }, "url": { "type": "string", "nullable": true, "description": "The primary website or social media account of the affiliate." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "affiliation_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "active": { "type": "boolean", "description": "Whether or not the affiliate is active." }, "affiliation_products": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated affiliation product objects." } ] }, "commission_structure": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated commission structure ID." }, { "$ref": "#/components/schemas/commission_structure_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated commission structure object." } ] }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this affiliation's correct portal page (hosted or external)." }, "referral_url": { "type": "string", "description": "The referral URL with the affiliate's code appended as a query parameter." }, "total_commission_amount": { "type": "integer", "description": "The total commission amount earned by the affiliate." }, "total_not_paid_commission_amount": { "type": "integer", "description": "The total commission amount earned by the affiliate that has not been paid out yet." }, "clicks": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated click objects." } ] }, "referrals": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated referral objects." } ] }, "payouts": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated payout objects." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "affiliation_product_body": { "allOf": [ { "properties": { "affiliation": { "type": "string", "description": "The UUID of the affiliation." }, "commission_structure": { "description": "The commission structure to use when calculating referral commissions for this product and affiliation.", "allOf": [ { "$ref": "#/components/schemas/commission_structure_base" } ] }, "product": { "type": "string", "description": "The UUID of the product." } } } ] }, "affiliation_product_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "affiliation": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "commission_structure": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated commission structure ID." }, { "$ref": "#/components/schemas/commission_structure_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated commission structure object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "affiliation_protocol_base": { "allOf": [ { "properties": { "affiliation_request_bio_label": { "type": "string", "nullable": true, "description": "The question affiliates are asked when they sign up." }, "affiliation_request_payout_email_enabled": { "type": "boolean", "description": "Whether or not to include the payout email field on the affiliation request form." }, "auto_approve_affiliations": { "type": "boolean", "description": "Whether or not to automatically approve affiliation requests." }, "auto_approve_referrals": { "type": "boolean", "description": "Whether or not to automatically approve referrals." }, "description": { "type": "string", "nullable": true, "description": "A short description of how this store's affiliate program works. This will be displayed when affiliates request to join." }, "enabled": { "type": "boolean", "description": "Whether or not this store is accepting new affiliation requests." }, "external_portal_enabled": { "type": "boolean", "description": "Whether or not an external affiliate portal is being used. If true, affiliates will be redirected to the store's URL when they visit the hosted affiliate portal." }, "external_portal_url": { "type": "string", "nullable": true, "description": "If `external_portal_enabled=true`, where is the external portal hosted? If empty, the store's URL is used." }, "payout_description": { "type": "string", "nullable": true, "description": "A short description of how this store pays out commissions to affiliates." }, "portal_back_url": { "type": "string", "nullable": true, "description": "The back URL that is shown to affiliates on the affiliate portal." }, "portal_heading": { "type": "string", "nullable": true, "description": "The heading to display in the affiliate portal sidebar." }, "portal_description": { "type": "string", "nullable": true, "description": "The short description to display in the affiliate portal sidebar." }, "referral_urls": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "An array of URLs that can be used for affiliate referrals. These will be used to generate affiliate referral links and shown to affiliates." }, "referrer_type": { "type": "string", "description": "The referrer strategy to use for referrals – one of `first` or `last`." }, "terms_url": { "type": "string", "nullable": true, "description": "The URL to the terms and conditions for this store's affiliate program." }, "tracking_length_days": { "type": "integer", "description": "The number of days to track affiliate clicks for. This determines how long the click tracking cookie will last for." }, "wordpress_plugin_tracking_enabled": { "type": "boolean", "description": "Whether or not the WordPress plugin should automatically add the tracking script." }, "zero_commission_amount_referrals_enabled": { "type": "boolean", "description": "Whether or not to create a referral from a checkout when the resulting referral has a `commission_amount` of 0." } } } ] }, "affiliation_protocol_body": { "allOf": [ { "$ref": "#/components/schemas/affiliation_protocol_base" }, { "properties": { "commission_structure": { "description": "The commission structure to use when calculating referral commissions.", "allOf": [ { "$ref": "#/components/schemas/commission_structure_base" } ] } } } ] }, "affiliation_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/affiliation_protocol_base" }, { "properties": { "commission_structure": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated commission structure ID." }, { "$ref": "#/components/schemas/commission_structure_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated commission structure object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "affiliation_request_body": { "allOf": [ { "properties": { "bio": { "type": "string", "description": "A short blurb from this affiliate describing how they will promote this store." }, "email": { "type": "string", "description": "The affiliate's email address." }, "first_name": { "type": "string", "description": "The affiliate's first name." }, "last_name": { "type": "string", "nullable": true, "description": "The affiliate's last name." }, "payout_email": { "type": "string", "nullable": true, "description": "The affiliate's payout email address." }, "url": { "type": "string", "nullable": true, "description": "The primary website or social media account of the affiliate." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "affiliation_request_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/affiliation_request_body" }, { "properties": { "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this affiliation request's correct portal page (hosted or external)." }, "status": { "type": "string", "description": "The current status of this affiliation request, which can be one of `approved`, `denied`, or `pending`." }, "used": { "type": "boolean", "description": "Whether or not the request has been used to register an affiliate." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "rule_condition": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "condition" ], "description": "Indicates this object is a condition." }, "attribute_name": { "type": "string", "description": "The attribute being checked (e.g., `subtotal_amount`)." }, "operator_label": { "type": "string", "description": "The operator used for comparison (e.g., `is_more_than`)." }, "comparison_value": { "type": "string", "description": "The value to compare against." } } }, "rule_group": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "group" ], "description": "Indicates this object is a group." }, "combinator": { "type": "string", "enum": [ "and", "or" ], "description": "Whether all conditions/groups must match (`and`) or any (`or`)." }, "conditions": { "type": "array", "description": "Nested conditions or groups.", "items": { "oneOf": [ { "$ref": "#/components/schemas/rule_condition" }, { "$ref": "#/components/schemas/rule_group" } ] } } } }, "auto_fee_base": { "properties": { "enabled": { "type": "boolean", "description": "Whether the auto fee is enabled." }, "amount_adjustment": { "type": "integer", "nullable": true, "description": "The amount in cents to be added or subtracted from subtotal of applicable checkout" }, "discount": { "type": "boolean", "description": "Whether this auto fee is a discount (subtracted from total) or a fee (added to total)." }, "end_at": { "type": "integer", "nullable": true, "description": "Time at which the auto fee becomes inactive. Measured in seconds since the Unix epoch." }, "fee_target": { "type": "string", "enum": [ "checkout", "line_item", "shipping" ], "description": "The entity to which this auto fee applies. (This can only be set when the auto fee is created.)" }, "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format." }, "name": { "type": "string", "description": "The name of the auto fee." }, "percent_adjustment": { "type": "number", "format": "float", "nullable": true, "description": "The percentage to be added or subtracted from subtotal of applicable checkout." }, "rules": { "nullable": true, "description": "The rules that determine when this auto fee applies", "oneOf": [ { "$ref": "#/components/schemas/rule_condition" }, { "$ref": "#/components/schemas/rule_group" } ] }, "start_at": { "type": "integer", "description": "Time at which the auto fee becomes active. Measured in seconds since the Unix epoch." } } }, "auto_fee_body": { "allOf": [ { "$ref": "#/components/schemas/auto_fee_base" } ] }, "auto_fee_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/auto_fee_base" }, { "properties": { "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "expired": { "type": "boolean", "description": "Whether the auto fee has expired." }, "ongoing": { "type": "boolean", "description": "Whether the auto fee is currently active." } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "auto_fee_protocol_base": { "type": "object", "properties": { "negative_checkout_fee_selection_strategy": { "type": "string", "description": "Determines how negative fees (discounts) applied at the checkout level are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] }, "negative_line_item_fee_selection_strategy": { "type": "string", "description": "Determines how negative fees (discounts) applied at the line-item level are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] }, "negative_shipping_fee_selection_strategy": { "type": "string", "description": "Determines how negative fees (discounts) applied to shipping are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] }, "positive_checkout_fee_selection_strategy": { "type": "string", "description": "Determines how positive fees applied at the checkout level are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] }, "positive_line_item_fee_selection_strategy": { "type": "string", "description": "Determines how positive fees applied at the line-item level are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] }, "positive_shipping_fee_selection_strategy": { "type": "string", "description": "Determines how positive fees applied to shipping are selected when multiple applicable fees exist. - `all`: Apply all matching fees. - `biggest`: Apply only the fee with the largest monetary impact. - `lowest`: Apply only the fee with the smallest monetary impact. - `first`: Apply the first matching fee based on creation order.\n", "enum": [ "all", "biggest", "lowest", "first" ] } } }, "auto_fee_protocol_body": { "allOf": [ { "$ref": "#/components/schemas/auto_fee_protocol_base" } ] }, "auto_fee_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/auto_fee_protocol_base" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "balance_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "amount": { "type": "integer", "description": "The total balance amount for this customer in this currency." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "balance_transactions": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated balance transaction objects." } ] }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "balance_transaction_base": { "properties": { "amount": { "type": "integer", "description": "The amount of the transaction. A negative value is a credit for the customer’s balance, and a positive value is a debit to the customer’s balance." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." } } }, "balance_transaction_body": { "allOf": [ { "$ref": "#/components/schemas/balance_transaction_base" }, { "properties": { "customer": { "type": "string", "description": "The UUID of the customer." } } } ] }, "balance_transaction_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/balance_transaction_base" }, { "properties": { "balance": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated balance ID." }, { "$ref": "#/components/schemas/balance_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated balance object." } ] }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "ending_balance_amount": { "type": "integer", "description": "The balance amount after the transaction was applied." }, "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "transaction_type": { "type": "string", "description": "One of either `adjustment`, `applied_to_checkout`, `checkout_below_currency_minimum`, or `checkout_credit`. Balance transactions created through the API are always `adjustment` transactions." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "batch_body": { "allOf": [ { "properties": { "batch_operations": { "type": "array", "description": "Array of operations to execute in this batch.", "items": { "$ref": "#/components/schemas/batch_operation_body" } } } } ] }, "batch_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "finished_batch_operations_count": { "type": "integer", "description": "The number of operations that have finished processing (completed, failed, or timed out)." }, "batch_operations_count": { "type": "integer", "description": "The total number of operations in this batch." }, "status": { "type": "string", "description": "The status of the batch. Possible values include:\n- `completed`: All operations in the batch have finished processing.\n- `in_progress`: The batch operations are currently being executed.\n- `pending`: The batch has been created but processing has not yet started.\n" }, "batch_operations": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of operations associated with this batch." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "batch_operation_body": { "allOf": [ { "properties": { "body": { "type": "object", "nullable": true, "description": "The JSON request body for this operation." }, "http_method": { "type": "string", "description": "The HTTP method for this operation – one of `DELETE`, `GET`, `PATCH`, `POST`, or `PUT`." }, "path": { "type": "string", "description": "The API path for this operation. Must start with `/` and contain only valid URL characters." }, "query_params": { "type": "object", "nullable": true, "description": "The query parameters for this operation." } } } ] }, "batch_operation_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/batch_operation_body" }, { "properties": { "response_body": { "type": "object", "nullable": true, "description": "The JSON response body returned by this operation." }, "response_status": { "type": "integer", "nullable": true, "description": "The HTTP response status code returned by this operation." }, "status": { "type": "string", "description": "The status of this operation. Possible values include:\n- `completed`: The operation was executed and a response was received.\n- `failed`: The operation encountered an internal error and could not be executed.\n- `in_progress`: The operation is currently being executed.\n- `pending`: The operation has not yet started execution.\n- `timed_out`: The operation exceeded the allowed execution time.\n" }, "batch": { "nullable": true, "anyOf": [ { "type": "string", "description": "The batch this operation belongs to.\n\n[Expandable](/api-reference/expanding-responses) – The associated batch ID." }, { "$ref": "#/components/schemas/batch_response", "description": "The batch this operation belongs to.\n\n[Expanded](/api-reference/expanding-responses) – The associated batch object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "brand_base": { "properties": { "color": { "type": "string", "nullable": true, "description": "The primary brand color. Used for buttons, links, loading states, etc." }, "dark_color": { "type": "string", "nullable": true, "description": "The primary brand color in dark mode. Used for buttons, links, loading states, etc." }, "email": { "type": "string", "nullable": true, "description": "The email address that will be shown to customers for support, on statements, etc." }, "phone": { "type": "string", "nullable": true, "description": "The phone number that will be shown to customers for support, on statements, etc." }, "theme": { "type": "string", "description": "The color theme for all store branded pages (i.e. affiliate portal). One of `light` or `dark`." }, "website": { "type": "string", "nullable": true, "description": "The website that will be shown to customers for support, on statements, etc." } } }, "brand_body": { "allOf": [ { "$ref": "#/components/schemas/brand_base" }, { "properties": { "dark_logo": { "type": "string", "description": "The UUID of the media that will be used as the dark mode logo on all store branded pages and emails." }, "logo": { "type": "string", "description": "The UUID of the media that will be used as the logo on all store branded pages and emails." }, "address": { "description": "The associated address.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] } } } ] }, "brand_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/brand_base" }, { "properties": { "dark_logo": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "logo": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "bulk_action_body": { "allOf": [ { "properties": { "action_type": { "type": "string", "description": "The type of action to be performed. Possible values include:\n- `delete_customers`\n- `delete_products`\n" }, "record_ids": { "type": "array", "description": "The id of records to perform the bulk action on." } } } ] }, "bulk_action_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/bulk_action_body" }, { "properties": { "skipped_record_ids": { "type": "array", "description": "The array of ids that are skipped due to the action not being applicable to them." }, "status": { "type": "string", "description": "The status of the bulk action. Possible values include:\n- `completed`: The bulk action has been executed, possibly with some errors.\n- `invalid`: The bulk action contains no record_ids that support the given action.\n- `pending`: The bulk action is pending and not yet processed.\n- `processing`: The bulk action is currently being processed.\n- `succeeded`: The bulk action has succeeded with no errors for all the supporting record_ids.\n" } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "bump_base": { "allOf": [ { "properties": { "amount_off": { "type": "integer", "nullable": true, "description": "Amount (in the `currency` of the price) that will be taken off line items associated with this bump." }, "archived": { "type": "boolean", "description": "Whether or not this bump is archived." }, "auto_apply": { "type": "boolean", "description": "Whether or not this bump should be automatically applied to applicable checkouts. If `false`, this bump must be manually added to a `line_item`." }, "filter_match_type": { "type": "string", "nullable": true, "description": "The matching strategy to use when filtering bumps – can be `null` or one of `all`, `any`, `none`. If `null`, the bump will not be filtered and will be applicable to all line items." }, "filter_price_ids": { "type": "array", "description": "The prices to filter this bump by." }, "filter_product_ids": { "type": "array", "description": "The products to filter this bump by." }, "name": { "type": "string", "nullable": true, "description": "A name for this bump that will be visible to customers." }, "percent_off": { "type": "number", "nullable": true, "description": "Percent that will be taken off line items associated with this bump." }, "priority": { "type": "integer", "description": "The priority of this bump in relation to other bumps. Must be in the range of `1` - `5` with `5` being the highest priority and `1` being the lowest." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "bump_body": { "allOf": [ { "$ref": "#/components/schemas/bump_base" }, { "properties": { "price": { "type": "string", "description": "The UUID of the price." } } } ] }, "bump_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/bump_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "bundle_item_base": { "allOf": [ { "properties": { "basis_amount": { "type": "integer", "nullable": true, "description": "Optional relative weighting input (in cents) for this component. Nil uses default weighting by quantity." }, "quantity": { "type": "integer", "description": "The quantity of this component in the bundle." }, "position": { "type": "integer", "nullable": true, "description": "The position of this item within the bundle." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "bundle_item_body": { "allOf": [ { "$ref": "#/components/schemas/bundle_item_base" }, { "properties": { "bundle_product": { "type": "string", "description": "The UUID of the bundle product." }, "component_product": { "type": "string", "description": "The UUID of the component product." } } } ] }, "bundle_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/bundle_item_base" }, { "properties": { "bundle_product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated bundle product ID." }, { "$ref": "#/components/schemas/bundle_product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated bundle product object." } ] }, "component_product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated component product ID." }, { "$ref": "#/components/schemas/component_product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated component product object." } ] }, "current_version": { "type": "boolean", "description": "Whether the returned version is the current one on the bundle item." }, "component_variants": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – The variants belonging to the component product." } ] }, "component_variant_options": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – The variant options belonging to the component product." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "cancellation_act_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "comment": { "type": "string", "nullable": true, "description": "The comment left by the customer when they canceled the subscription." }, "coupon_applied": { "type": "boolean", "description": "Whether or not the preservation coupon was applied to the subscription when it was preserved." }, "performed_at": { "type": "integer", "description": "Time at which the cancellation act was performed. Measured in seconds since the Unix epoch." }, "preserved": { "type": "boolean", "description": "Whether or not this subscription was preserved when the customer went to cancel it." }, "cancellation_reason": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated cancellation reason ID." }, { "$ref": "#/components/schemas/cancellation_reason_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated cancellation reason object." } ] }, "subscription": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated subscription ID." }, { "$ref": "#/components/schemas/subscription_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated subscription object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "cancellation_reason_body": { "properties": { "archived": { "type": "boolean", "description": "Whether or not this cancellation reason is archived." }, "comment_enabled": { "type": "boolean", "description": "Whether or not this cancellation reason should prompt the user for a comment." }, "comment_prompt": { "type": "string", "nullable": true, "description": "A breif customer-facing prompt for more detail that will be shown when this cancellation reason is selected." }, "coupon_enabled": { "type": "boolean", "description": "Whether or not this cancellation reason should offer the `subscription_protocol.cancellation_prevention_coupon` to the customer to preserve the subscription." }, "label": { "type": "string", "description": "The customer-facing label for this cancellation reason." }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this cancellation reason when displayed to customers." } } }, "cancellation_reason_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/cancellation_reason_body" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "card_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "brand": { "type": "string", "description": "The brand of the card, which can be `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, or `unknown`." }, "exp_month": { "type": "integer", "description": "Two-digit number representing the card’s expiration month." }, "exp_year": { "type": "integer", "description": "Four-digit number representing the card’s expiration year." }, "last4": { "type": "string", "description": "The last four digits of the card." }, "wallet_type": { "type": "string", "nullable": true, "description": "If this card is part of a card wallet, this will be set to the type of wallet. The current types are `amex_express_checkout`, `apple_pay`, `google_pay`, `masterpass`, `samsung_pay`, or `visa_checkout`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "charge_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "amount": { "type": "integer", "description": "The amount in cents that was charged, represented as a whole integer. For example `9900` is equivalent to `$99`." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "disputed_amount": { "type": "integer", "description": "The amount in cents that has been disputed." }, "external_charge_id": { "type": "string", "description": "The external processor ID representing this charge." }, "fully_refunded": { "type": "boolean", "description": "Whether or not this charge has been refunded completely." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this charge is in live mode, and set to `false` if it is in test mode." }, "refunded_amount": { "type": "integer", "description": "Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued)." }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "disputes": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated dispute objects." } ] }, "payment_intent": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment intent ID." }, { "$ref": "#/components/schemas/payment_intent_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment intent object." } ] }, "payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment method ID." }, { "$ref": "#/components/schemas/payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment method object." } ] }, "refunds": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated refund objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "checkout_base": { "allOf": [ { "properties": { "abandoned_checkout_enabled": { "type": "boolean", "nullable": true, "description": "If set to `true` abandonded checkout reminder emails will be sent to the customer." }, "billing_matches_shipping": { "type": "boolean", "description": "If set to `true` the shipping address will be used for the billing address." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This value will match the `Account` currency." }, "email": { "type": "string", "nullable": true, "description": "The email of the customer. If customers exists with this email, the most recently active/updated customer will be associated. If no customers exist with this email, a new customer will be created. If a `customer_id` is also passed then this will take precedence and the customer will not be looked up by email." }, "external_url": { "type": "string", "nullable": true, "description": "If set, this URL will be used whenever redirecting to the external checkout portal. If not set, the default `external_url` from the `CheckoutPortalProtocol` will be used." }, "first_name": { "type": "string", "nullable": true, "description": "The customer’s first name." }, "ip_address": { "type": "string", "nullable": true, "description": "The IP address of the customer for this checkout." }, "group_key": { "type": "string", "nullable": true, "description": "A key used to retrieve groups of checkouts dynamically from a static string." }, "last_name": { "type": "string", "nullable": true, "description": "The customer’s last name." }, "latitude": { "type": "number", "nullable": true, "description": "The latitude captured for this checkout, in decimal degrees." }, "longitude": { "type": "number", "nullable": true, "description": "The longitude captured for this checkout, in decimal degrees." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this checkout is in live mode, and set to `false` if it is in test mode." }, "name": { "type": "string", "nullable": true, "description": "The customer’s full name or business name. If set, this will take precedence over the separate `first_name` and `last_name` attributes." }, "tax_behavior": { "type": "string", "description": "The tax behavior for this checkout. One of `exclusive` or `inclusive`." }, "tax_enabled": { "type": "boolean", "description": "Whether or not tax is enabled for this checkout. This will default to the account's `tax_protocol.tax_enabled` value when the checkout is created." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "checkout_body": { "allOf": [ { "$ref": "#/components/schemas/checkout_base" }, { "properties": { "billing_address": { "description": "The billing address for this checkout.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] }, "customer": { "type": "string", "description": "The UUID of the customer. (The customer can't be changed once the checkout has been paid.)" }, "discount": { "description": "The parameters of the discount to be applied to this checkout.", "allOf": [ { "$ref": "#/components/schemas/discount_body" } ] }, "line_items": { "type": "array", "description": "A list of this checkout's line items. (The line items can't be updated through the checkout once it has been paid.)", "items": { "$ref": "#/components/schemas/line_item_body" } }, "refresh_line_items": { "type": "boolean", "nullable": true, "description": "When set to true the prices and variants that are associated with each line item will be refreshed to reference the most recent version. (This should be used if you are receiving an error when trying to finalize a checkout that is referencing old price versions and/or variant versions.)" }, "selected_shipping_choice": { "type": "string", "description": "The UUID of the shipping choice." }, "shipping_address": { "description": "The shipping address for this checkout.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] }, "tax_identifier": { "description": "The tax identifier to set for this checkout.", "allOf": [ { "$ref": "#/components/schemas/tax_identifier_body" } ] } } } ] }, "checkout_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/checkout_base" }, { "properties": { "amount_due": { "type": "integer", "description": "Total amount due after all adjustments (i.e. trials, credits, proration)." }, "applied_balance_amount": { "type": "integer", "description": "The customer balance amount that was applied to this checkout." }, "available_countries": { "type": "array", "description": "A list of countries available for this checkout, represented in the two-letter (ISO 3166-1 alpha-2) format." }, "billing_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "charges": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated charge objects." } ] }, "checkout_fees": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated checkout fee objects." } ] }, "checkout_fees_amount": { "type": "integer", "description": "The total amount of checkout fees applied to this checkout." }, "credited_balance_amount": { "type": "integer", "description": "The amount the customer's balance was credited from this checkout." }, "current_payment_intent": { "nullable": true, "anyOf": [ { "type": "string", "description": "The current payment intent to be used to pay the checkout. (This will only be set once the checkout has been finalized.)\n\n[Expandable](/api-reference/expanding-responses) – The associated payment intent ID." }, { "$ref": "#/components/schemas/payment_intent_response", "description": "The current payment intent to be used to pay the checkout. (This will only be set once the checkout has been finalized.)\n\n[Expanded](/api-reference/expanding-responses) – The associated payment intent object." } ] }, "current_upsell": { "nullable": true, "anyOf": [ { "type": "string", "description": "The upsell to be shown to the customer. (This will only be set once the checkout has been paid and an upsell funnel is set on the checkout.)\n\n[Expandable](/api-reference/expanding-responses) – The associated upsell ID." }, { "$ref": "#/components/schemas/upsell_response", "description": "The upsell to be shown to the customer. (This will only be set once the checkout has been paid and an upsell funnel is set on the checkout.)\n\n[Expanded](/api-reference/expanding-responses) – The associated upsell object." } ] }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "The customer will only be set once the checkout has been finalized.\n\n[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "The customer will only be set once the checkout has been finalized.\n\n[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "discount": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated discount ID." }, { "$ref": "#/components/schemas/discount_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated discount object." } ] }, "discount_amount": { "type": "integer", "description": "Total discount amount of all line items." }, "geo_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "free_shipping_choice_shortage_amount": { "type": "integer", "nullable": true, "description": "The amount that needs to be added to the checkout to qualify for free shipping. If `null`, then a free shipping choice is not available or it has already qualified." }, "full_amount": { "type": "integer", "description": "The full amount to be charged across all periods." }, "g_weight": { "type": "number", "description": "Total weight of the entire checkout in grams." }, "inherited_billing_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "The inherited billing address of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "The inherited billing address of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "inherited_email": { "type": "string", "nullable": true, "description": "The inherited email of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol." }, "inherited_name": { "type": "string", "nullable": true, "description": "The inherited name of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol." }, "inherited_phone": { "type": "string", "nullable": true, "description": "The inherited phone of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol." }, "inherited_shipping_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "The inherited shipping address of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "The inherited shipping address of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "inherited_tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "The inherited tax identifier of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expandable](/api-reference/expanding-responses) – The associated tax identifier ID." }, { "$ref": "#/components/schemas/tax_identifier_response", "description": "The inherited tax identifier of the checkout or customer. This is controlled by the `inherit_customer_enabled` attribute on the account's order protocol.\n\n[Expanded](/api-reference/expanding-responses) – The associated tax identifier object." } ] }, "invoice": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated invoice ID." }, { "$ref": "#/components/schemas/invoice_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated invoice object." } ] }, "last_click": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated click ID." }, { "$ref": "#/components/schemas/click_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated click object." } ] }, "line_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated line item objects." } ] }, "manual_charges": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated manual charge objects." } ] }, "manual_payment": { "type": "boolean", "description": "Whether or not this checkout has been finalized with the `manual_payment=true` option." }, "manual_payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated manual payment method ID." }, { "$ref": "#/components/schemas/manual_payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated manual payment method object." } ] }, "remaining_amount_due": { "type": "integer", "description": "The remaining amount that is due for this checkout – the `amount_due` - `paid_amount`." }, "net_paid_amount": { "type": "integer", "description": "The net amount that has been paid for this checkout – the `paid_amount` minus the `refunded_amount`." }, "order": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated order ID." }, { "$ref": "#/components/schemas/order_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated order object." } ] }, "paid_amount": { "type": "integer", "description": "The total amount that has been paid for this checkout – the sum of charges and manual charges." }, "paid_at": { "type": "integer", "nullable": true, "description": "Time at which the object was paid. Measured in seconds since the Unix epoch." }, "payment_failures": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated payment failure objects." } ] }, "payment_method_required": { "type": "boolean", "description": "Whether or not a payment method is required for this checkout. If false, the checkout will immediately transition to the `paid` state when finalized." }, "phone_required": { "type": "boolean", "description": "Whether or not a phone number is required for this checkout. (This is determined by the account's active payment processors.)" }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this checkout's correct portal page (hosted or external)." }, "processor_data": { "type": "object", "description": "All of the additional data necessary to capture payment with each processor." }, "proration_amount": { "type": "integer", "description": "Total amount to be prorated from this checkout." }, "purchases": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated purchase objects." } ] }, "recommended_bumps": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of recommended bumps for this checkout." } ] }, "referral": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated referral ID." }, { "$ref": "#/components/schemas/referral_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated referral object." } ] }, "refunded_amount": { "type": "integer", "description": "The total amount that has been refunded for this checkout – the sum of refunds." }, "reusable_payment_method_required": { "type": "boolean", "description": "Whether or not a reusable payment method is required for this checkout." }, "selected_shipping_choice_required": { "type": "boolean", "description": "Whether or not a shipping choice must be selected for this checkout." }, "selected_shipping_choice": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping choice ID." }, { "$ref": "#/components/schemas/shipping_choice_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping choice object." } ] }, "shipping_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "shipping_address_accuracy_requirement": { "type": "string", "nullable": true, "description": "The required level of accuracy for the shipping address – one of `full`, `tax`, or `none`." }, "shipping_amount": { "type": "integer", "description": "Total shipping amount for the checkout." }, "shipping_choices": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of available shipping choices for this checkout." } ] }, "shipping_fees": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated shipping fee objects." } ] }, "shipping_enabled": { "type": "boolean", "description": "Whether or not this checkout has products with `shipping_enabled=true`." }, "shipping_fees_amount": { "type": "integer", "description": "The total amount of shipping fees applied to the shipping_amount." }, "shipping_tax_amount": { "type": "number", "description": "Total tax from shipping." }, "shipping_tax_rate": { "type": "number", "description": "The tax rate applied to shipping." }, "status": { "type": "string", "description": "The current status of this checkout, which can be one of `canceled`, `draft`, `finalized`, `paid`, `payment_intent_canceled`, `payment_failed`, or `processing`." }, "subtotal_amount": { "type": "integer", "description": "Total of all line items and their fees before discounts or taxes are applied." }, "tax_amount": { "type": "integer", "description": "Total tax amount of all line items." }, "tax_breakdown": { "type": "array", "description": "The tax rate breakdown for this checkout." }, "tax_label": { "type": "string", "nullable": true, "description": "The type of tax that is applied to this checkout. For example, in the EU this value will be `VAT` and in the US this value will be `Tax`." }, "tax_status": { "type": "string", "description": "The status of tax calculations for this checkout. One of `address_invalid`, `calculated`, `disabled`, `estimated`, `reverse_charged`, or `tax_zone_not_found`." }, "tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax identifier ID." }, { "$ref": "#/components/schemas/tax_identifier_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax identifier object." } ] }, "total_amount": { "type": "integer", "description": "Total of all line items after discounts and taxes are applied." }, "total_savings_amount": { "type": "integer", "description": "The total amount in cents that was saved on this checkout taking into account all negative fees, discounts, and all price `scratch_amount` values." }, "trial_amount": { "type": "integer", "description": "The total amount in cents that is removed from this checkout due to trial periods." }, "upsells_expire_at": { "type": "integer", "nullable": true, "description": "The time at which upsells will expire for this checkout. Measured in seconds since the Unix epoch." }, "upsell_funnel": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated upsell funnel ID." }, { "$ref": "#/components/schemas/upsell_funnel_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated upsell funnel object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "checkout_fee_base": { "properties": { "amount": { "type": "integer", "description": "The amount in cents to be added or subtracted, represented as an integer. For example `9900` is equivalent to `$99`." }, "description": { "type": "string", "description": "A short description of the checkout fee." } } }, "checkout_fee_body": { "allOf": [ { "$ref": "#/components/schemas/checkout_fee_base" }, { "properties": { "checkout": { "type": "string", "description": "The UUID of the checkout." } } } ] }, "checkout_fee_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/checkout_fee_base" }, { "properties": { "fee_type": { "type": "string", "description": "The type of checkout_fee – one of `auto` or `manual`." }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "checkout_portal_protocol_body": { "properties": { "back_url": { "type": "string", "nullable": true, "description": "The back URL that is shown to customers on the checkout portal. This can be overridden by a `back_url` on a `Checkout`." }, "external_enabled": { "type": "boolean", "description": "Whether or not an external checkout portal is being used." }, "external_url": { "type": "string", "nullable": true, "description": "If `external_enabled=true`, where is the external portal hosted? If empty, the store's URL is used." }, "manual_checkout_finalize_enabled": { "type": "boolean", "description": "Whether or not finalizing a checkout with `manual_payment=true` is allowed." }, "thank_you_heading": { "type": "string", "nullable": true, "description": "The heading that is shown to customers on the order thank you page." }, "thank_you_description": { "type": "string", "nullable": true, "description": "The description that is shown to customers on the order thank you page." }, "wordpress_plugin_enabled": { "type": "boolean", "description": "Whether or not the WordPress plugin is hosting the checkout portal." } } }, "checkout_portal_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/checkout_portal_protocol_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "click_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "anonymous_id": { "type": "string", "description": "The anonymous ID used for identifying a customer across multiple clicks." }, "converted": { "type": "boolean", "description": "Whether or not this click is associated with any referrals." }, "domain": { "type": "string", "description": "The domain of the click." }, "expires_at": { "type": "integer", "description": "Time at which the click expires. Measured in seconds since the Unix epoch." }, "referrer": { "type": "string", "nullable": true, "description": "The referring URL that the customer came from." }, "url": { "type": "string", "description": "The URL where the click was tracked." }, "affiliation": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "previous_click": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated click ID." }, { "$ref": "#/components/schemas/click_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated click object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "commission_structure_base": { "properties": { "amount_commission": { "type": "number", "nullable": true, "description": "The default amount (in the `currency` of the store) of commission to be paid." }, "percent_commission": { "type": "number", "nullable": true, "description": "The percentage of the checkout total to be paid to affiliates." }, "recurring_commissions_enabled": { "type": "boolean", "description": "Whether or not to pay affiliates recurring commissions on subscriptions." }, "recurring_commission_days": { "type": "integer", "nullable": true, "description": "The number of days to pay recurring commissions for." }, "repeat_customer_commissions_enabled": { "type": "boolean", "description": "Whether or not to pay commissions to affiliates for repeat customers." }, "repeat_customer_commission_days": { "type": "integer", "nullable": true, "description": "The number of days to pay commissions for repeat customers." } } }, "contact_base": { "properties": { "name": { "type": "string", "description": "The full name of the contact." }, "email": { "type": "string", "description": "The email address of the contact." }, "company": { "type": "string", "nullable": true, "description": "The company name of the contact." }, "phone": { "type": "string", "nullable": true, "description": "The phone number of the contact." } } }, "contact_body": { "allOf": [ { "$ref": "#/components/schemas/contact_base" }, { "properties": { "address": { "description": "The address for this contact.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] } } } ] }, "contact_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/contact_base" }, { "properties": { "address": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "coupon_base": { "allOf": [ { "properties": { "archived": { "type": "boolean", "description": "Whether or not this coupon is archived." }, "amount_off": { "type": "integer", "nullable": true, "description": "Amount (in the `currency` specified) that will be taken off the subtotal of any checkout." }, "duration": { "type": "string", "description": "One of `forever`, `once`, and `repeating`. Describes how long a discount with this coupon will be applied. (The `repeating` and `forever` values only apply to subscriptions.)", "default": "once" }, "duration_in_months": { "type": "integer", "nullable": true, "description": "If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`." }, "max_redemptions": { "type": "integer", "nullable": true, "description": "Maximum number of times this coupon can be redeemed in total across all customers." }, "max_redemptions_per_customer": { "type": "integer", "nullable": true, "description": "Maximum number of times this coupon can be redeemed per customer." }, "max_subtotal_amount": { "type": "integer", "nullable": true, "description": "The maximum `subtotal_amount` that is allowed for the coupon to be applicable to a checkout or subscription." }, "min_subtotal_amount": { "type": "integer", "nullable": true, "description": "The minimum `subtotal_amount` that is required for the coupon to be applicable to a checkout or subscription." }, "name": { "type": "string", "description": "Name of the coupon displayed to customers." }, "percent_off": { "type": "number", "nullable": true, "description": "Percent that will be taken off the subtotal of any checkout. For example, a coupon with percent_off of `50` will make a $100 checkout $50 instead." }, "product_ids": { "type": "array", "description": "An array of product IDs that this coupon applies to." }, "redeem_by": { "type": "integer", "nullable": true, "description": "Date after which the coupon can no longer be redeemed." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "coupon_body": { "allOf": [ { "$ref": "#/components/schemas/coupon_base" }, { "properties": { "promotions": { "type": "array", "description": "A list of this product's promotions. (This can only be set when creating a new coupon.)", "items": { "$ref": "#/components/schemas/promotion_body" } } } } ] }, "coupon_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/coupon_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This value will match the `Account` currency." }, "discounts": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated discount objects." } ] }, "expired": { "type": "boolean", "description": "Taking into account the above properties, whether this coupon can still be applied to a checkout." }, "promotions": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated promotion objects." } ] }, "times_redeemed": { "type": "integer", "description": "Number of times this coupon has been applied to a checkout and/or subscription." } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "customer_base": { "properties": { "affiliation_expires_at": { "type": "integer", "nullable": true, "description": "Time at which the affiliation will expire." }, "billing_matches_shipping": { "type": "boolean", "description": "If set to `true` the shipping address will be used for the billing address." }, "email": { "type": "string", "description": "The customer’s email address." }, "first_name": { "type": "string", "nullable": true, "description": "The customer’s first name." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this customer is in live mode, and set to `false` if it is in test mode." }, "last_name": { "type": "string", "nullable": true, "description": "The customer’s last name." }, "name": { "type": "string", "nullable": true, "description": "The customer’s full name or business name. If set, this will take precedence over the separate `first_name` and `last_name` attributes." }, "phone": { "type": "string", "nullable": true, "description": "The customer’s phone number." }, "tax_enabled": { "type": "boolean", "description": "Whether or not tax should be calculated for checkouts associated with this customer." }, "unsubscribed": { "type": "boolean", "description": "Set to `true` if this customer has unsubscribed from from opt-in emails (i.e. abandoned cart emails)." } } }, "customer_body": { "allOf": [ { "$ref": "#/components/schemas/customer_base" }, { "properties": { "affiliation": { "type": "string", "description": "The affiliation associated with this customer." }, "billing_address": { "description": "The billing address for the customer.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] }, "default_payment_method": { "type": "string", "description": "The UUID of the default payment method." }, "shipping_address": { "description": "The shipping address for the customer.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] }, "tax_identifier": { "description": "The tax identifier to set for this customer.", "allOf": [ { "$ref": "#/components/schemas/tax_identifier_body" } ] } } } ] }, "customer_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/customer_base" }, { "properties": { "first_name": { "type": "string", "nullable": true, "description": "The customer’s first name." }, "indexed": { "type": "boolean", "description": "Whether or not this customer is included in the `/customers` list endpoint. Only customers that have been manually created or have a purchase are indexed." }, "last_name": { "type": "string", "nullable": true, "description": "The customer’s last name." }, "affiliation": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "balances": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of this customer's balances." } ] }, "billing_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "default_payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment method ID." }, { "$ref": "#/components/schemas/payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment method object." } ] }, "licenses": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated license objects." } ] }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this customer's correct portal page (hosted or external)." }, "purchases": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated purchase objects." } ] }, "shipping_address": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax identifier ID." }, { "$ref": "#/components/schemas/tax_identifier_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax identifier object." } ] }, "reviews": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated review objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "customer_link_body": { "properties": { "customer": { "type": "string", "description": "The UUID of the customer." } } }, "customer_link_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "expired": { "type": "boolean", "description": "Whether or not this customer link is valid." }, "first_used_at": { "type": "integer", "nullable": true, "description": "Date when the customer link was first used." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "customer_notification_protocol_body": { "properties": { "free_order_enabled": { "type": "boolean", "description": "Whether or not order confirmation and subscription renewal emails will be sent to customers when the order is free." }, "notifications_enabled": { "type": "boolean", "description": "Whether or not any notifications should be sent to customers. If `false` no notifications will be sent to customers and all other settings will be ignored." }, "order_enabled": { "type": "boolean", "description": "Whether or not order confirmation emails will be sent to customers." }, "payment_failure_enabled": { "type": "boolean", "description": "Whether or not subscription dunning emails will be sent to customers." }, "purchase_enabled": { "type": "boolean", "description": "Whether or not product access emails will be sent to customers." }, "refund_enabled": { "type": "boolean", "description": "Whether or not refund emails will be sent to customers." }, "subscription_cancellation_enabled": { "type": "boolean", "description": "Whether or not subscription cancellation emails will be sent to customers." }, "subscription_reminder_enabled": { "type": "boolean", "description": "Whether or not subscription reminder emails will be sent to customers." }, "subscription_renewal_enabled": { "type": "boolean", "description": "Whether or not subscription renewal emails will be sent to customers." }, "from_name": { "type": "string", "nullable": true, "description": "The from name to use when sending emails to customers." }, "reply_to_email": { "type": "string", "nullable": true, "description": "The reply-to email address to use when sending emails to customers." }, "upsell_accepted_enabled": { "type": "boolean", "description": "Whether or not post purchase offer accepted emails will be sent to customers." } } }, "customer_notification_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/customer_notification_protocol_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "customer_portal_protocol_body": { "properties": { "back_url": { "type": "string", "nullable": true, "description": "The back URL that is shown to customers on the customer portal. This can be overridden by a `back_url` on a `CustomerPortalSession`." }, "external_enabled": { "type": "boolean", "description": "Whether or not an external customer portal is being used." }, "external_url": { "type": "string", "nullable": true, "description": "If `external_enabled=true`, where is the external portal hosted? If empty, the store's URL is used." }, "login_enabled": { "type": "boolean", "description": "Whether or not customer's can login with their email and a verification code on the hosted customer portal. If disabled, the only way to authenticate a customer is with a `CustomerPortalSession`." }, "privacy_url": { "type": "string", "nullable": true, "description": "The privacy policy link that is shown to customers on the customer portal." }, "subscription_cancellations_enabled": { "type": "boolean", "description": "Whether or not customers can cancel subscriptions from the customer portal." }, "subscription_updates_enabled": { "type": "boolean", "description": "Whether or not customers can make subscription changes from the customer portal." }, "subscription_quantity_updates_enabled": { "type": "boolean", "description": "Whether or not customers can change subscription quantities from the customer portal." }, "terms_url": { "type": "string", "nullable": true, "description": "The terms of service link that is shown to customers on the customer portal." }, "wordpress_plugin_enabled": { "type": "boolean", "description": "Whether or not the WordPress plugin is hosting the customer portal." } } }, "customer_portal_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/customer_portal_protocol_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "discount_body": { "properties": { "coupon": { "type": "string", "description": "The UUID of the coupon." }, "promotion_code": { "type": "string", "description": "The customer-facing code that will be used to lookup the promotion." } } }, "discount_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "discount_amount": { "type": "integer", "description": "The total discount amount applied to the associated checkout." }, "primary": { "type": "boolean", "description": "Whether or not this discount is a primary or secondary discount. Primary discounts are the first discount in a series of discounts when the associated coupon can be used multiple times. Secondary discounts are the subsequent discounts in the series." }, "redeemable_status": { "type": "string", "description": "The status indicating if this discount can be redeemed (finalized with) or not and why. Possible values are `invalid`, `gone`, `expired`, `less_than_min_subtotal_amount`, greater_than_max_subtotal_amount`, `not_applicable`, `not_applicable_to_customer`, or `redeemable`." }, "used_up": { "type": "boolean", "description": "Whether or not this discount has been used up. If not used up, this discount will create secondary discounts on future checkouts." }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "coupon": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated coupon ID." }, { "$ref": "#/components/schemas/coupon_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated coupon object." } ] }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "primary_discount": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated discount ID." }, { "$ref": "#/components/schemas/discount_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated discount object." } ] }, "promotion": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated promotion ID." }, { "$ref": "#/components/schemas/promotion_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated promotion object." } ] }, "secondary_discounts": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated discount objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "display_currency_body": { "properties": { "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." } } }, "display_currency_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/display_currency_body" }, { "properties": { "current_exchange_rate": { "type": "number", "description": "The current exchange rate from the account's default currency to this display currency." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "dispute_base": { "allOf": [ { "properties": { "amount": { "type": "integer", "description": "The amount in cents that is disputed, represented as a whole integer. For example `9900` is equivalent to `$99`." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "external_dispute_id": { "type": "string", "description": "The external processor ID representing this dispute." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this dispute is in live mode, and set to `false` if it is in test mode." }, "processor_type": { "type": "string", "description": "The type of associated processor – one of `mock`, `mollie`, `paypal`, `paystack`, or `stripe`." }, "status": { "type": "string", "description": "The current status of this dispute, which can be one of `pending`, `won`, or `lost`." } } } ] }, "dispute_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/dispute_base" }, { "properties": { "charge": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated charge ID." }, { "$ref": "#/components/schemas/charge_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated charge object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "download_base": { "properties": { "alt": { "type": "string", "nullable": true, "description": "The HTML alt attribute for the download." }, "archived": { "type": "boolean", "description": "Whether or not this download is archived." }, "name": { "type": "string", "nullable": true, "description": "The name of this download which will be visible to customers. This is required if a `url` is used instead of attaching a `Media` record." }, "title": { "type": "string", "nullable": true, "description": "The HTML title attribute for the download." }, "url": { "type": "string", "nullable": true, "description": "Instead of attaching a `Media` record a public URL can be set. If set, customers will be directed to this URL." } } }, "download_body": { "allOf": [ { "$ref": "#/components/schemas/download_base" }, { "properties": { "media": { "type": "string", "description": "The UUID of the media." }, "product": { "type": "string", "description": "The UUID of the product." }, "variant": { "type": "string", "description": "The UUID of the variant." } } } ] }, "download_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/download_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "media": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "variant": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "event_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "account": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated account ID." }, { "$ref": "#/components/schemas/account_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated account object." } ] }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in seconds since the Unix epoch." }, "type": { "type": "string", "description": "Description of the event (e.g., subscription.updated or charge.updated)." } } } ] }, "export_body": { "allOf": [ { "properties": { "type": { "type": "string", "description": "The type of export – one of `charges`, `coupons`, `customers`, `orders`, `prices`, `promotions`, `refunds`, `subscriptions`." }, "email": { "type": "string", "description": "The email where the export will be sent." } } } ] }, "export_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/export_body" }, { "properties": { "file_url": { "type": "string", "nullable": true, "description": "The URL for accessing the export file." }, "status": { "type": "string", "description": "The status of the export – one of `pending`, `processed`, or `sent`." }, "record_count": { "type": "number", "description": "The number of records that were exported." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "fee_base": { "properties": { "amount": { "type": "integer", "description": "The amount in cents to be added or subtracted, represented as an integer. For example `9900` is equivalent to `$99`." }, "description": { "type": "string", "description": "A short description of the fee." } } }, "fee_body": { "allOf": [ { "$ref": "#/components/schemas/fee_base" }, { "properties": { "line_item": { "type": "string", "description": "The UUID of the line_item." } } } ] }, "fee_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/fee_base" }, { "properties": { "fee_type": { "type": "string", "description": "The type of fee – one of `auto`, `bump`, `manual`, `setup`, `upsell`." }, "line_item": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated line item ID." }, { "$ref": "#/components/schemas/line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated line item object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "fulfillment_base": { "allOf": [ { "properties": { "notifications_enabled": { "type": "boolean", "description": "Whether or not notifications should be sent to customers when fulfillments are created and updated." }, "shipment_status": { "type": "string", "description": "The current shipment status of this fulfillment – one of `unshippable`, `unshipped`, `label_purchased`, `shipped`, `in_transit`, `delivered`, `returned`, or `failed`." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "fulfillment_body": { "allOf": [ { "$ref": "#/components/schemas/fulfillment_base" }, { "properties": { "order": { "type": "string", "description": "The UUID of the order." }, "fulfillment_items": { "type": "array", "description": "A list of this fulfillement's items.", "items": { "$ref": "#/components/schemas/fulfillment_item_body" } }, "trackings": { "type": "array", "description": "A list of this fulfillement's trackings.", "items": { "$ref": "#/components/schemas/tracking_body" } }, "shipments": { "type": "array", "description": "A list of this fulfillment's shipments.", "items": { "$ref": "#/components/schemas/shipment_body" } } } } ] }, "fulfillment_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/fulfillment_base" }, { "properties": { "g_weight": { "type": "number", "description": "Total weight of the entire fulfillment in grams." }, "number": { "type": "string", "description": "The unique identifier for this fulfillment that is auto generated based on this account's order protocol." }, "order": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated order ID." }, { "$ref": "#/components/schemas/order_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated order object." } ] }, "fulfillment_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated fulfillment item objects." } ] }, "trackings": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated tracking objects." } ] }, "shipments": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated shipment objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "fulfillment_item_base": { "allOf": [ { "properties": { "quantity": { "type": "integer", "description": "The quantity of products being fulfilled. This must be less than or equal to the remaining unfulfilled quantity of the associated line item." } } } ] }, "fulfillment_item_body": { "allOf": [ { "$ref": "#/components/schemas/fulfillment_item_base" }, { "properties": { "line_item": { "type": "string", "description": "The UUID of the line item." } } } ] }, "fulfillment_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/fulfillment_item_base" }, { "properties": { "g_weight": { "type": "number", "description": "Total weight of all items (quantity * unit_g_weight) in grams." }, "unit_g_weight": { "type": "number", "description": "Total weight of the product in grams." }, "fulfillment": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated fulfillment ID." }, { "$ref": "#/components/schemas/fulfillment_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated fulfillment object." } ] }, "line_item": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated line item ID." }, { "$ref": "#/components/schemas/line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated line item object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "product_import_body": { "allOf": [ { "$ref": "#/components/schemas/product_body" }, { "properties": { "prices": { "type": "array", "description": "Array of prices to create for this product.", "items": { "$ref": "#/components/schemas/price_base" } }, "product_medias": { "type": "array", "description": "Array of product media to attach to this product.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the media to attach." } } } } } } ] }, "import_products_body": { "properties": { "data": { "type": "array", "description": "Array of products to import.", "items": { "$ref": "#/components/schemas/product_import_body" } } } }, "import_coupons_body": { "properties": { "data": { "type": "array", "description": "Array of coupons to import.", "items": { "$ref": "#/components/schemas/coupon_body" } } } }, "import_product_collections_body": { "properties": { "data": { "type": "array", "description": "Array of product collections to import.", "items": { "$ref": "#/components/schemas/product_collection_body" } } } }, "import_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "import_type": { "type": "string", "description": "The type of record imported – one of `customer`, `product`, `coupon`, `purchase`, or `subscription`." }, "import_rows": { "type": "array", "description": "A list of associated import rows." }, "rows_imported": { "type": "integer", "description": "The number of rows successfully imported." }, "status": { "type": "string", "description": "The status of the import – one of `completed`, `invalid`, `pending`, or `processing`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "import_row_base": { "properties": { "failure_reason": { "type": "string", "nullable": true, "description": "The reason for the import failure, if applicable." }, "import_data": { "type": "object", "description": "The data to be imported." }, "import_row_type": { "type": "string", "description": "The type of record to import – one of `coupon` or `product`" }, "status": { "type": "string", "description": "The status of the import row – one of `pending`, `succeeded`, or `failed`." } } }, "import_row_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/import_row_base" }, { "properties": { "import": { "type": "string", "description": "The UUID of associated import." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "invoice_body": { "allOf": [ { "properties": { "automatic_collection": { "type": "boolean", "description": "Whether or not the invoice should be paid automatically using one of the customer's payment methods. The specific payment method will need to passed to the `/open` endpoint." }, "due_date": { "type": "integer", "nullable": true, "description": "The date on which payment for this invoice is due. Measured in seconds since the Unix epoch." }, "footer": { "type": "string", "nullable": true, "description": "Additional footer text to be displayed on the invoice." }, "issue_date": { "type": "integer", "nullable": true, "description": "The date on which the invoice was issued. Measured in seconds since the Unix epoch." }, "live_mode": { "type": "boolean", "description": "Whether or not the invoice is in live mode." }, "memo": { "type": "string", "nullable": true, "description": "Additional memo text to be displayed on the invoice." }, "notifications_enabled": { "type": "boolean", "description": "Whether or not notifications should be sent to customers when an invoice is opened and when it reaches its due date." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "invoice_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/invoice_body" }, { "properties": { "notification_sent_at": { "type": "integer", "nullable": true, "description": "The time at which the invoice notification was sent. Measured in seconds since the Unix epoch." }, "order_number": { "type": "string", "nullable": true, "description": "The order number associated with this invoice." }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this invoice's correct portal page (hosted or external)." }, "reminder_notification_sent_at": { "type": "integer", "nullable": true, "description": "The time at which the reminder notification was sent. Measured in seconds since the Unix epoch." }, "status": { "type": "string", "description": "The current status of this invoice, which can be one of `draft`, `open`, `paid` or void." }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "license_base": { "properties": { "activation_limit": { "type": "integer", "nullable": true, "description": "The max number of activations allowed. If set to `null` then unlimited activations are allowed." }, "key": { "type": "string", "description": "The unique identifier for this license. The default generated value is a UUID, but this can be set to any unique value within the scope of this account." } } }, "license_body": { "allOf": [ { "$ref": "#/components/schemas/license_base" }, { "properties": { "purchase": { "type": "string", "description": "The UUID of the purchase." } } } ] }, "license_base_response": { "allOf": [ { "$ref": "#/components/schemas/license_base" }, { "properties": { "activations_count": { "type": "integer", "description": "The current number of activations." }, "revokes_at": { "type": "integer", "nullable": true, "description": "Time at which the license will be revoked. Measured in seconds since the Unix epoch." }, "status": { "type": "string", "description": "The status of this license which is one of `active`, `inactive`, or `revoked`. If the associated purchase is revoked then the license will be `revoked`. If the license has one or more activations then it will be `active`, otherwise it will be `inactive`." } } } ] }, "license_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/license_base_response" }, { "properties": { "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "purchase": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated purchase ID." }, { "$ref": "#/components/schemas/purchase_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated purchase object." } ] }, "activations": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated activation objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "line_item_base": { "properties": { "ad_hoc_amount": { "type": "integer", "nullable": true, "description": "The amount to use for this line item when the associated price is `ad_hoc=true`." }, "bundle_component_variants": { "type": "object", "description": "A hash mapping bundle component product UUIDs (keys) to the selected variant UUIDs (values) for each component." }, "quantity": { "type": "integer", "description": "The quantity of products being purchased." }, "note": { "type": "string", "nullable": true, "description": "A custom note for this line item. Useful for adding context or special instructions related to the product or purchase." } } }, "line_item_body": { "allOf": [ { "$ref": "#/components/schemas/line_item_base" }, { "properties": { "bump": { "type": "string", "description": "The UUID of the bump." }, "checkout": { "type": "string", "description": "The UUID of the checkout." }, "price": { "type": "string", "description": "The UUID of the price." }, "upsell": { "type": "string", "description": "The UUID of the upsell." }, "variant": { "type": "string", "description": "The UUID of the variant." } } } ] }, "line_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/line_item_base" }, { "properties": { "bump": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated bump ID." }, { "$ref": "#/components/schemas/bump_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated bump object." } ] }, "bundle_line_item": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated bundle line item ID." }, { "$ref": "#/components/schemas/bundle_line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated bundle line item object." } ] }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "checkout_fees_amount": { "type": "integer", "description": "The total amount of checkout fees applied to this line item." }, "component_line_item": { "type": "boolean", "description": "Whether or not this line item is a component of a bundle." }, "position": { "type": "integer", "nullable": true, "description": "The position of this line item. For bundle component line items, this mirrors the source bundle item's position so components render in a stable order across cart, checkout, and order payloads." }, "discount_amount": { "type": "integer", "description": "Total discount amount applied to this line item." }, "fees": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated fee objects." } ] }, "fees_amount": { "type": "integer", "description": "The total amount of fees applied to this line item." }, "full_amount": { "type": "integer", "description": "The full amount to be charged across all periods." }, "fulfilled_quantity": { "type": "integer", "description": "The quantity of products that have been fulfilled." }, "g_weight": { "type": "number", "description": "Total weight of all items (quantity * unit_g_weight) in grams." }, "locked": { "type": "boolean", "description": "Whether or not this line item is locked. If locked, it cannot be edited or deleted. Line items are locked when an invoice is opened." }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "purchasable_status": { "type": "string", "description": "The status indicating if this line item can be purchased (finalized with) or not and why. Possible values are `price_gone`, `price_old_version`, `variant_mising`, `variant_gone`, `variant_old_version`, `out_of_stock`, `exceeds_purchase_limit`, or `purchasable`." }, "scratch_amount": { "type": "integer", "description": "The amount in cents that should be shown as the original amount before any price reductions, also known as the pre-sale price." }, "stock_held": { "type": "boolean", "description": "Whether or not stock is being held for this line item. (This only applies to the quantity that has not been fulfilled.)" }, "subtotal_amount": { "type": "integer", "description": "Total before any discounts or taxes are applied." }, "swap": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated swap ID." }, { "$ref": "#/components/schemas/swap_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated swap object." } ] }, "tax_amount": { "type": "integer", "description": "Total tax amount." }, "tax_rate": { "type": "number", "description": "The tax rate for this line item." }, "total_amount": { "type": "integer", "description": "Total after discounts and taxes are applied." }, "total_savings_amount": { "type": "integer", "description": "The total amount in cents that was saved on this line item taking into account all negative fees, discounts, and all price `scratch_amount` values." }, "trial": { "type": "boolean", "description": "Set to `true` if this line item is for a price that has a trial." }, "trial_amount": { "type": "integer", "description": "The total amount in cents that is removed from this line item due to a trial period." }, "unit_dimensions_cm": { "type": "object", "nullable": true, "description": "The physical dimensions of this line item's product/variant in centimeters.", "properties": { "length": { "type": "number", "description": "The length dimension." }, "width": { "type": "number", "description": "The width dimension." }, "height": { "type": "number", "description": "The height dimension." }, "unit": { "type": "string", "description": "The unit of measurement (always `cm`)." } } }, "unit_g_weight": { "type": "number", "description": "The weight per unit of product in grams." }, "upsell": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated upsell ID." }, { "$ref": "#/components/schemas/upsell_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated upsell object." } ] }, "variant": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] }, "variant_options": { "type": "array", "nullable": true, "description": "An array of the associated variant's options." }, "variant_option_names": { "type": "array", "nullable": true, "description": "An array of the associated product's variant option names." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "manual_charge_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "amount": { "type": "integer", "description": "The amount in cents that was charged, represented as a whole integer. For example `9900` is equivalent to `$99`." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "manual_payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated manual payment method ID." }, { "$ref": "#/components/schemas/manual_payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated manual payment method object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "manual_payment_method_body": { "properties": { "archived": { "type": "boolean", "description": "Whether or not this manual payment method is archived." }, "description": { "type": "string", "nullable": true, "description": "The description of this payment method that will be shown in the checkout." }, "instructions": { "type": "string", "nullable": true, "description": "The instructions that you want your customers to follow to pay for an order. These instructions are shown on the confirmation page after a customer completes the checkout." }, "name": { "type": "string", "description": "The name of this manual payment method." }, "reuseable": { "type": "boolean", "decription": "Whether or not this manual payment method can be reused." } } }, "manual_payment_method_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/manual_payment_method_body" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "media_body": { "properties": { "alt": { "type": "string", "nullable": true, "description": "The HTML alt attribute for the media." }, "direct_upload_signed_id": { "type": "string", "description": "The signed_id from the direct upload." }, "title": { "type": "string", "nullable": true, "description": "The HTML title attribute for the media." } } }, "media_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "byte_size": { "type": "integer", "description": "The size of the media in bytes." }, "content_type": { "type": "string", "description": "The content type (i.e. image/png, image/jpg, application/pdf)." }, "extension": { "type": "string", "description": "The extension (i.e. png, jpg, pdf)." }, "filename": { "type": "string", "description": "The full filename with extension." }, "height": { "type": "string", "nullable": true, "description": "If the media is an image, this will be the height in pixels." }, "public_access": { "type": "boolean", "description": "Whether or not this media is publicly accessible." }, "release_json": { "type": "object", "nullable": true, "description": "The JSON that was extracted from the `release.json` file within the ZIP file." }, "url": { "type": "string", "nullable": true, "description": "The URL for accessing this media. If the media is public, this will be a permanent URL. If the media is private, this will be a short-lived URL if the media has been exposed." }, "url_expires_at": { "type": "integer", "nullable": true, "description": "The time at which the URL expires. This will only be present if the media is private and has been exposed." }, "width": { "type": "string", "nullable": true, "description": "If the media is an image, this will be the width in pixels." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "note_body": { "allOf": [ { "properties": { "notable_type": { "type": "string", "description": "The type of object that this note belongs to – one of `customer`, `order`, or `subscription`." }, "notable_id": { "type": "string", "description": "The ID of the object that this note belongs to." }, "body": { "type": "string", "description": "The body of the note." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "note_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/note_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "order_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "fulfillment_status": { "type": "string", "description": "The overall fulfillment status of this order based on all fulfillments – one of `fulfilled`, `partially_fulfilled`, or `unfulfilled`." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this order is in live mode, and set to `false` if it is in test mode." }, "number": { "type": "string", "description": "The unique identifier for this order that is auto generated based on this account's order protocol." }, "order_type": { "type": "string", "description": "One of either `checkout` or `subscription`." }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this order's correct portal page (hosted or external)." }, "return_status": { "type": "string", "description": "The overall return status of this order based on all return requests – one of `not_returned`, `partially_returned`, `return_request_open`, or `returned`." }, "shipment_status": { "type": "string", "description": "The overall shipment status of this order based on all fulfillments – one of `unshippable`, `unshipped`, `partially_shipped`, `label_purchased`, `shipped`, `in_transit`, or `delivered`." }, "statement_url": { "type": "string", "nullable": true, "description": "The link to view and download the \"invoice\" or \"receipt\" statement of this order." }, "status": { "type": "string", "description": "The current status of this order, which can be one of `draft`, `paid`, `payment_failed`, `processing`, or `void`." }, "fulfillments": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated fulfillment objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "order_protocol_body": { "properties": { "capture_geo_address_enabled": { "type": "boolean", "description": "Whether or not to reverse-geocode the latitude and longitude captured on checkouts into a `geo_address`." }, "inherit_customer_enabled": { "type": "boolean", "description": "Each order has a series of attributes `inherited_billing_address`, `inherited_shipping_address`, `inherited_tax_identifier`, `inherited_name`, `inherited_phone`, and `inherited_email`.\nIf this is enabled, the order will inherit these attributes from the customer when they are not present on the associated checkout.\nThis allows changes to a customers details to be reflected on past orders and statements." }, "footer": { "type": "string", "nullable": true, "description": "The default footer that is shown on all order statements (i.e. invoices and receipts)." }, "memo": { "type": "string", "nullable": true, "description": "The default memo that is shown on all order statements (i.e. invoices and receipts)." }, "next_sequential_number": { "type": "integer", "description": "Specified to change the next sequential number to be used. If changed, must be larger than the highest current sequential number." }, "number_prefix": { "type": "string", "nullable": true, "description": "The prefix that is added to all order numbers. Must be between 3-12 characters and only include letters." }, "number_type": { "type": "string", "description": "The type of number to use for orders – one of `sequential` or `token`." }, "require_reusable_payment_methods": { "type": "boolean", "decription": "Whether or not to force all payment methods to be reusable even if a checkout does not contain a subscription." }, "upsells_expire_after_minutes": { "type": "integer", "description": "The number of minutes after an order is paid that upsells will be available for." } } }, "order_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/order_protocol_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "parcel_template_body": { "properties": { "default": { "type": "boolean", "description": "If set to `true`, this parcel template will be set as the account's default parcel template." }, "name": { "type": "string", "description": "A name for this parcel template." }, "package_type": { "type": "string", "description": "The type of package – one of `box`, `poly_mailer`." }, "dimensions": { "type": "object", "nullable": true, "description": "The physical dimensions of this parcel template.", "properties": { "length": { "type": "number", "description": "The length dimension." }, "width": { "type": "number", "description": "The width dimension." }, "height": { "type": "number", "description": "The height dimension." }, "unit": { "type": "string", "description": "The unit of measurement – one of `cm`, `mm`, `m`, `in`, `ft`." } } }, "weight": { "type": "number", "nullable": true, "description": "The weight of this parcel template." }, "weight_unit": { "type": "string", "description": "The weight unit for this parcel template – one of `lb`, `oz`, `kg`, `g`." } } }, "parcel_template_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/parcel_template_body" }, { "properties": { "default": { "type": "boolean", "description": "Whether or not this parcel template is the account's default." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "payment_intent_base": { "properties": { "amount": { "type": "integer", "description": "The amount intended to be collected by this payment intent." }, "payment_method_type": { "type": "string", "description": "The payment method type to use for this payment intent. This is only applicable for `mollie` processors." }, "return_url": { "type": "string", "description": "The URL the customer will be redirected to after the payment process. This is only applicable for `mollie` processors." } } }, "payment_intent_full_base": { "allOf": [ { "$ref": "#/components/schemas/payment_intent_base" }, { "properties": { "live_mode": { "type": "boolean", "description": "Set to `true` if this checkout is in live mode, and set to `false` if it is in test mode." }, "processor_type": { "type": "string", "description": "The processor being used for this checkout. The only allowed processors right now are `stripe` and `paypal`." } } } ] }, "payment_intent_body": { "allOf": [ { "$ref": "#/components/schemas/payment_intent_full_base" }, { "properties": { "customer": { "type": "string", "description": "The UUID of the customer." } } } ] }, "payment_intent_update_body": { "allOf": [ { "$ref": "#/components/schemas/payment_intent_base" }, { "properties": { "customer": { "type": "string", "description": "The UUID of the customer." } } } ] }, "payment_intent_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/payment_intent_full_base" }, { "properties": { "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This value will match the `Account` currency." }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "external_intent_id": { "type": "string", "description": "The external ID necessary to capture payment through this processor. For example, if processing through Stripe, the `external_intent_id` will be set to the `Stripe::PaymentIntent` ID." }, "off_session": { "type": "boolean", "description": "Set to true to indicate that the customer is not in the checkout flow during the payment attempt. When `off_session=true` payment collection will be attempted immediately." }, "payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment method ID." }, { "$ref": "#/components/schemas/payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment method object." } ] }, "platform_fee": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated platform fee ID." }, { "$ref": "#/components/schemas/platform_fee_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated platform fee object." } ] }, "processor_data": { "type": "object", "description": "All of the additional data necessary to capture payment with this processor." }, "reusable": { "type": "boolean", "description": "Whether or not the payment method that is generated from this payment intent should be reusable or not." }, "service_fee": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated service fee ID." }, { "$ref": "#/components/schemas/service_fee_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated service fee object." } ] }, "status": { "type": "string", "description": "The status of this payment intent, one of `pending`, `canceled`, `failed`, `processing`, `requires_action`, `requires_capture`, or `succeeded`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "payment_method_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "external_payment_method_id": { "type": "string", "description": "The external processor ID representing this payment method." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this charge is in live mode, and set to `false` if it is in test mode." }, "processor_type": { "type": "string", "description": "The specific type of processor. The only allowed processors right now are `stripe` and `paypal`." }, "reusable": { "type": "boolean", "description": "Whether or not this payment method can be reused. Only reusable payment methods can be attached to subscriptions and set as a customer's default." }, "supported_currencies": { "type": "array", "nullable": true, "description": "A list of currencies that this payment method supports. If `null`, this payment method supports all currencies." }, "type": { "type": "string", "description": "The type of payment method. One of `bank_account, `card`, `payment_instrument`, or `paypal_account`." }, "bank_account": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated bank account ID." }, { "$ref": "#/components/schemas/bank_account_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated bank account object." } ] }, "card": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated card ID." }, { "$ref": "#/components/schemas/card_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated card object." } ] }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "payment_instrument": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment instrument ID." }, { "$ref": "#/components/schemas/payment_instrument_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment instrument object." } ] }, "paypal_account": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated paypal account ID." }, { "$ref": "#/components/schemas/paypal_account_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated paypal account object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "payout_base": { "properties": { "description": { "type": "string", "nullable": true, "description": "An optional brief description of what this payout is for." }, "end_date": { "type": "integer", "description": "All approved referrals through this day will be included in the payout." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this payout is in live mode, and set to `false` if it is in test mode." }, "manual": { "type": "boolean", "description": "Whether or not this payout was created manually or automatically from approved referrals." }, "total_commission_amount": { "type": "integer", "description": "The amount in cents that will be paid out to the affiliate. For manual payouts, this is set directly. For automatic payouts, this is calculated from the sum of approved referrals." } } }, "payout_body": { "allOf": [ { "$ref": "#/components/schemas/payout_base" }, { "properties": { "affiliation": { "type": "string", "description": "The UUID of the affiliation." } } } ] }, "payout_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/payout_base" }, { "properties": { "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. If not set, this value will fallback to the default `Account` currency." }, "status": { "type": "string", "description": "The status of the payout – one of `completed` or `processing`." }, "affiliation": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "payout_group": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payout group ID." }, { "$ref": "#/components/schemas/payout_group_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payout group object." } ] }, "payout_email": { "type": "string", "nullable": true, "description": "The affiliate's payout email address." }, "referrals": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated referral objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "payout_group_body": { "properties": { "end_date": { "type": "integer", "description": "All approved referrals through this day will be included in the payout." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this payout group is in live mode, and set to `false` if it is in test mode." }, "min_commission_amount": { "type": "integer", "nullable": true, "description": "The minimum amount of commission that must be earned before a payout is generated for an affiliate." } } }, "payout_group_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/payout_group_body" }, { "properties": { "currency": { "type": "string", "description": "The currency of the payout group." }, "payouts": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated payout objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "period_body": { "properties": { "end_at": { "type": "integer", "nullable": true, "description": "End of the period. This will be `null` when the period is for a subscription with a one-time price." } } }, "period_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/period_body" }, { "properties": { "ad_hoc_amount": { "type": "integer", "nullable": true, "description": "The amount to use for this period when the associated price is `ad_hoc=true`." }, "next_payment_retry_at": { "type": "integer", "nullable": true, "description": "The time at which payment will be automatically retried." }, "payment_retry_count": { "type": "integer", "description": "Number of payment retries made for this period, from the perspective of the payment retry schedule. Only automatic retries increment the count." }, "payoff": { "type": "boolean", "description": "Indicates whether or not this period paid off all remaining periods." }, "quantity": { "type": "integer", "description": "The quantity of products being purchased." }, "renewal": { "type": "boolean", "description": "Whether or not this period has been generated automatically for a subscription renewal." }, "renewal_reminder_sent_at": { "type": "integer", "nullable": true, "description": "The time at which the renewal reminder notification was sent to the customer." }, "restoral": { "type": "boolean", "description": "Whether or not this period was generated from a subscription restoral." }, "skip_proration": { "type": "boolean", "description": "Whether or not proration should be skipped when generating this period's checkout." }, "start_at": { "type": "integer", "nullable": true, "description": "Start of the period." }, "status": { "type": "string", "description": "The current status of this period, which can be one of `pending`, `payment_failed`, `paid`, `processing`, or `void`." }, "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "subscription": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated subscription ID." }, { "$ref": "#/components/schemas/subscription_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated subscription object." } ] }, "variant": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "price_base": { "allOf": [ { "properties": { "ad_hoc": { "type": "boolean", "default": false, "description": "Whether or not this price accepts ad hoc amounts – also known as custom or user-defined amounts." }, "ad_hoc_max_amount": { "type": "integer", "nullable": true, "description": "The maximum ad hoc amount in cents to be allowed, represented as a whole integer. For example `9900` is equivalent to `$99`." }, "ad_hoc_min_amount": { "type": "integer", "nullable": true, "description": "The minimum ad hoc amount in cents to be allowed, represented as a whole integer. For example `9900` is equivalent to `$99`. If left blank, this will be interpreted as `0`." }, "amount": { "type": "integer", "nullable": true, "description": "The amount in cents to be charged, represented as a whole integer. For example `9900` is equivalent to `$99`. If `ad_hoc=true` the `amount` is optional." }, "archived": { "type": "boolean", "description": "Whether or not this price is archived." }, "license_activation_limit": { "type": "integer", "nullable": true, "description": "The max number of activations allowed per license. If `null`, this value will inherit from the value set on `Product`." }, "name": { "type": "string", "nullable": true, "description": "The price name, meant to be displayable to the customer." }, "portal_subscription_update_enabled": { "type": "boolean", "description": "Whether existing subscriptions can be switched to this price from the customer dashboard. If set to false, existing subscriptions cannot be switched to this price, preventing customers from upgrading or downgrading their subscription to this price option." }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this price when displayed to customers." }, "recurring_interval": { "type": "string", "nullable": true, "description": "The frequency at which a subscription is billed. One of `day`, `week`, `month`, or `year`. Only applicable during creation." }, "recurring_interval_count": { "type": "integer", "nullable": true, "description": "The number of intervals (specified in the `recurring_interval` attribute) between subscription billings. For example, `recurring_interval=month` and `recurring_interval_count=3` bills every 3 months. The total duration of a billing cycle is not allowed to exceed 1 year. Only applicable during creation." }, "recurring_period_count": { "type": "integer", "nullable": true, "description": "The number of periods a subscription with this price will renew for. After this amount of periods, the subscription will move to the `complete` state. Only applicable during creation." }, "revoke_after_days": { "type": "integer", "nullable": true, "description": "The number of days after which the purchase associated with this price will be automatically revoked. This can be used to create time-limited access for a one-time or finite recurring price." }, "revoke_purchases_on_completed": { "type": "boolean", "description": "Whether or not purchases for this price should be revoked when subscriptions transition to the `complete` state." }, "restart_subscription_on_completed": { "type": "boolean", "description": "Whether installment subscriptions using this price should be automatically restarted when they reach the completed state." }, "setup_fee_amount": { "type": "integer", "nullable": true, "description": "The amount in cents to be charged as a setup fee on the first billing period of a recurring price." }, "setup_fee_enabled": { "type": "boolean", "description": "Whether or not this price has a setup fee." }, "setup_fee_name": { "type": "string", "nullable": true, "description": "The name that will display for the setup fee on the first billing period." }, "setup_fee_trial_enabled": { "type": "boolean", "description": "Whether or not the setup fee should be deferred until the trial period ends. If set to true, the setup fee will not be charged until the trial period ends." }, "scratch_amount": { "type": "integer", "nullable": true, "description": "The amount in cents that should be shown as the original amount before any price reductions, also known as the pre-sale price." }, "trial_duration_days": { "type": "integer", "nullable": true, "description": "The default number of trial days when subscribing a customer to this price." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "price_body": { "allOf": [ { "$ref": "#/components/schemas/price_base" }, { "properties": { "product": { "type": "string", "description": "The UUID of the product. Only applicable during creation." }, "renewal_price": { "type": "string", "description": "The UUID of the renewal price." } } } ] }, "price_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/price_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This value will match the `Account` currency." }, "full_amount": { "type": "integer", "description": "The full amount to be charged across all periods, represented as a whole integer. For prices without a `recurring_period_count` defined this is the same as `amount`. For finite prices, this is equal to `amount` * `recurring_period_count`. For example, a price that has an amount of $25 and is set to recur over 4 periods, will have a `full_amount` of $100." }, "current_version": { "type": "boolean", "description": "Whether or not this object represents the current version of this price. (This will be `false` if the association was created to this price before it was altered. In this case, we will lookup the version of the price at the time it was associated.)" }, "current_swap": { "nullable": true, "anyOf": [ { "type": "string", "description": "The current swap for this price.\n\n[Expandable](/api-reference/expanding-responses) – The associated swap ID." }, { "$ref": "#/components/schemas/swap_response", "description": "The current swap for this price.\n\n[Expanded](/api-reference/expanding-responses) – The associated swap object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "renewal_price": { "nullable": true, "anyOf": [ { "type": "string", "description": "If present, subscriptions will be updated to this price when they renew.\n\n[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "If present, subscriptions will be updated to this price when they renew.\n\n[Expanded](/api-reference/expanding-responses) – The associated price object." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "processor_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "approved": { "type": "boolean", "description": "Whether or not the connected processor account has been approved to process payments. (This is controlled by the processing platform – i.e. Stripe, PayPal, etc.)" }, "enabled": { "type": "boolean", "description": "Whether or not this processor is currently enabled to proccess new payments. (This is controlled within SureCart.)" }, "live_mode": { "type": "boolean", "description": "Set to `true` if this processor is for live mode, and set to `false` if it is for test mode." }, "processor_type": { "type": "string", "description": "The type of processor – one of `mock`, `mollie`, `paypal`, `paystack`, or `stripe`." }, "processor_data": { "type": "object", "description": "Data that is specific to the `processor_type` and necessary for integrating with this processor on the client. For example, this could include client public keys, account IDs, etc." }, "recurring_enabled": { "type": "boolean", "description": "Whether or not this processor is setup to handle recurring payments." }, "supported_currencies": { "type": "array", "nullable": true, "description": "A list of currencies that this processor supports. If `null`, this processor supports all currencies." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "product_base": { "allOf": [ { "properties": { "allow_out_of_stock_purchases": { "type": "boolean", "description": "Whether or not to allow purchases of this product when stock runs out. If true, the stock levels for this can go below zero." }, "archived": { "type": "boolean", "description": "Whether or not this product is archived." }, "auto_fulfill_enabled": { "type": "boolean", "description": "Whether or not this product should be auto fulfilled when it is purchased. This can only be `true` when `shipping_enabled` is `false`." }, "cataloged_at": { "type": "integer", "description": "The time when the product was added or made available. This value is used for sorting products on shop pages." }, "description": { "type": "string", "nullable": true, "description": "The product description, meant to be displayable to the customer." }, "dimensions": { "type": "object", "nullable": true, "description": "The physical dimensions of this product for shipping calculations.", "properties": { "length": { "type": "number", "description": "The length dimension." }, "width": { "type": "number", "description": "The width dimension." }, "height": { "type": "number", "description": "The height dimension." }, "unit": { "type": "string", "description": "The unit of measurement – one of `cm`, `mm`, `m`, `in`, `ft`." } } }, "featured": { "type": "boolean", "description": "Whether or not this product is featured." }, "licensing_enabled": { "type": "boolean", "description": "Whether or not licensing is enabled for this product." }, "license_activation_limit": { "type": "integer", "nullable": true, "description": "The max number of activations allowed per license. If `null`, then unlimited license activations are allowed. (The activation limit can also be set on `Price` which will override this value.)" }, "name": { "type": "string", "description": "The product name, meant to be displayable to the customer." }, "purchase_limit": { "type": "integer", "nullable": true, "description": "The max number of times the product can be purchased by a customer. If `null`, then unlimited purchases are allowed." }, "recurring": { "type": "boolean", "default": false, "description": "Whether the product is for a one-time purchase or a recurring (subscription) purchase." }, "reviews_enabled": { "type": "boolean", "description": "Whether or not reviews are enabled for this product." }, "shipping_enabled": { "type": "boolean", "description": "If set to `true` checkouts with this product will require a full shipping address." }, "sku": { "type": "string", "nullable": true, "description": "The stock keeping unit for this product. If the `Product` has variants, each variant has a specific `sku`." }, "status": { "type": "string", "description": "The status of this product – one of `draft` or `published`." }, "slug": { "type": "string", "description": "A unique and URL friendly string that represents this product. (This will be auto-generated when a product is created if not explicitly set.)" }, "solicit_reviews": { "type": "boolean", "description": "Whether or not to solicit reviews for this product with automatic emails to customers." }, "stock_enabled": { "type": "boolean", "description": "Whether or not stock will be tracked for this product." }, "tax_category": { "type": "string", "nullable": true, "description": "The tax category/code that matches this product – one of `digital`, `tangible`, `service`, or `saas`." }, "tax_enabled": { "type": "boolean", "description": "If set to `true` this product is considered taxable." }, "weight": { "type": "number", "description": "The product weight, meant to be displayable to the customer." }, "weight_unit": { "type": "string", "description": "The weight unit for this product – one of `lb`, `oz`, `kg`, `g`." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "product_body": { "allOf": [ { "$ref": "#/components/schemas/product_base" }, { "properties": { "bundle_items": { "type": "array", "description": "A list of this product's bundle items.", "items": { "$ref": "#/components/schemas/bundle_item_body" } }, "commission_structure": { "description": "The commission structure to use when calculating referral commissions for this specific product.", "allOf": [ { "$ref": "#/components/schemas/commission_structure_base" } ] }, "current_release_download": { "type": "string", "description": "The UUID of the current release download." }, "product_collections": { "type": "array", "nullable": true, "description": "The UUIDs of all the product collections that this product belongs to." }, "product_collection_slugs": { "type": "array", "description": "Array of product collection slugs this product belongs to. (This allows you to associate the product with product collections by slug instead of UUID.)", "items": { "type": "string" } }, "product_group": { "type": "string", "description": "The UUID of the product group." }, "shipping_profile": { "type": "string", "description": "The UUID of the shipping profile." }, "stock_adjustment": { "type": "integer", "description": "The amount to adjust the stock by. This can be a positive or negative number." }, "reviews": { "type": "array", "description": "A list of associated reviews.", "items": { "$ref": "#/components/schemas/review_body" } }, "variant_options": { "type": "array", "description": "A list of this product's variant options.", "items": { "$ref": "#/components/schemas/variant_option_body" } }, "variants": { "type": "array", "description": "A list of this product's variants.", "items": { "$ref": "#/components/schemas/variant_body" } } } } ] }, "product_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/product_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "available_stock": { "type": "integer", "description": "The total amount of stock available for purchase. This is the total `stock` on hand minus `held_stock`." }, "average_stars": { "type": "string", "description": "The average stars for this product based on published reviews." }, "bundle_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated bundle item objects." } ] }, "commission_structure": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated commission structure ID." }, { "$ref": "#/components/schemas/commission_structure_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated commission structure object." } ] }, "current_release_download": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated download ID." }, { "$ref": "#/components/schemas/download_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated download object." } ] }, "held_stock": { "type": "integer", "description": "The total amount of stock being held by unfulfilled line items." }, "metrics": { "type": "object", "properties": { "currency": { "type": "string", "description": "The currency that was used to calculate these metrics. This will always be set to the account's currency." }, "max_price_amount": { "type": "integer", "nullable": true, "description": "The maximum `amount` among this product's prices (including variant price overrides)." }, "min_price_amount": { "type": "integer", "nullable": true, "description": "The minimum `amount` among this product's prices (including variant price overrides)." }, "prices_count": { "type": "integer", "nullable": true, "description": "The total number of prices that belong to this product." } } }, "downloads": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated download objects." } ] }, "reviews_breakdown": { "type": "object", "description": "A histogram breakdown of the reviews for this product." }, "featured_product_media": { "nullable": true, "anyOf": [ { "type": "string", "description": "The featured (first) product media.\n\n[Expandable](/api-reference/expanding-responses) – The associated product media ID." }, { "$ref": "#/components/schemas/product_media_response", "description": "The featured (first) product media.\n\n[Expanded](/api-reference/expanding-responses) – The associated product media object." } ] }, "prices": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated price objects." } ] }, "product_collections": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated product collection objects." } ] }, "product_group": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product group ID." }, { "$ref": "#/components/schemas/product_group_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product group object." } ] }, "product_medias": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated product media objects." } ] }, "shipping_profile": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping profile ID." }, { "$ref": "#/components/schemas/shipping_profile_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping profile object." } ] }, "stock": { "type": "integer", "description": "The total amount of stock on hand for this variant." }, "reviews": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated review objects." } ] }, "variant_options": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated variant option objects." } ] }, "variants": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated variant objects." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "product_collection_base": { "allOf": [ { "properties": { "name": { "type": "string", "description": "A name for this product collection that will be visible to customers." }, "description": { "type": "string", "description": "The product collection description, meant to be displayable to the customer.", "nullable": true }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this product collection when displayed to customers." }, "slug": { "type": "string", "description": "A unique and URL friendly string that represents this product collection. (This will be auto-generated when a product collection is created if not explicitly set.)" } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "product_collection_body": { "allOf": [ { "$ref": "#/components/schemas/product_collection_base" }, { "properties": { "image": { "type": "string", "description": "The UUID of the media." } } } ] }, "product_collection_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/product_collection_base" }, { "properties": { "image": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "products_count": { "type": "integer", "description": "The number of products in this collection." }, "products": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated product objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "product_group_body": { "allOf": [ { "properties": { "archived": { "type": "boolean", "description": "Whether or not this product group is archived." }, "name": { "type": "string", "description": "The product group’s name, meant to be displayable to the customer." }, "purchase_limit": { "type": "integer", "nullable": true, "description": "The max number of times the product group can be purchased by a customer. If `null`, then unlimited purchases are allowed." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "product_group_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/product_group_body" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "products": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated product objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "product_media_base": { "allOf": [ { "properties": { "alt": { "type": "string", "nullable": true, "description": "The HTML alt attribute for the product media." }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this product media when displayed to customers." }, "title": { "type": "string", "nullable": true, "description": "The HTML title attribute for the product media." }, "url": { "type": "string", "nullable": true, "description": "Instead of attaching a `Media` record, a public URL can be set. If set, this URL will be used to serve the product media asset." } } } ] }, "product_media_body": { "allOf": [ { "$ref": "#/components/schemas/product_media_base" }, { "properties": { "media": { "type": "string", "nullable": true, "description": "The UUID of the media." }, "product": { "type": "string", "description": "The UUID of the product." } } } ] }, "product_media_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/product_media_base" }, { "properties": { "media": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "promotion_base": { "allOf": [ { "properties": { "archived": { "type": "boolean", "description": "Whether or not this promotion is archived." }, "code": { "type": "string", "description": "The customer-facing code. Regardless of case, this code must be unique across all promotion codes on your account. If left blank, we will generate one automatically." }, "expired": { "type": "boolean", "description": "Whether or not this promotion has expired." }, "max_redemptions": { "type": "integer", "nullable": true, "description": "Maximum number of times this coupon can be redeemed in total across all customers." }, "redeem_by": { "type": "integer", "nullable": true, "description": "Date after which the coupon can no longer be redeemed." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "promotion_body": { "allOf": [ { "$ref": "#/components/schemas/promotion_base" }, { "properties": { "affiliation": { "type": "string", "nullable": true, "description": "The UUID of the affiliation" }, "coupon": { "type": "string", "description": "The UUID of the coupon." }, "customer": { "type": "string", "description": "The UUID of the customer." } } } ] }, "promotion_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/promotion_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "affiliation": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "coupon": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated coupon ID." }, { "$ref": "#/components/schemas/coupon_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated coupon object." } ] }, "customer": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "discounts": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated discount objects." } ] }, "expired": { "type": "boolean", "description": "Taking into account the above properties, whether this promotion can still be used." } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "public": { "account_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "name": { "type": "string", "description": "The account name." }, "slug": { "type": "string", "description": "The account slug." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "checkout_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/checkout_base" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "click_base": { "properties": { "referrer": { "type": "string", "nullable": true, "description": "The referrer of the click." }, "url": { "type": "string", "description": "The URL of the click." } } }, "click_body": { "allOf": [ { "$ref": "#/components/schemas/public/click_base" }, { "properties": { "affiliation_code": { "type": "string", "description": "The code of the associatied affiliation." } } } ] }, "click_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/public/click_base" }, { "properties": { "domain": { "type": "string", "description": "The domain of the click." }, "expires_at": { "type": "integer", "description": "Time at which the click expires. Measured in seconds since the Unix epoch." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "country_response": { "allOf": [ { "properties": { "address_formats": { "type": "object", "description": "The address formats of the country." }, "address_labels": { "type": "object", "description": "The address labels of the country." }, "city_required": { "type": "boolean", "description": "Whether the city is required for the country." }, "code": { "type": "string", "description": "The two-letter code of the country - ISO 3166-1." }, "name": { "type": "string", "description": "The full name of the country." }, "postal_code_required": { "type": "boolean", "description": "Whether the postal code is required for the country." }, "postal_code_regex": { "type": "string", "nullable": true, "description": "The regex pattern for validating postal codes in the country." }, "state_required": { "type": "boolean", "description": "Whether the state is required for the country." }, "states": { "type": "array", "description": "The states of the country.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the state - ISO 3166-2." }, "name": { "type": "string", "description": "The full name of the state." } } } } } } ] }, "license_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/license_base_response" }, { "properties": { "current_release": { "type": "string", "nullable": true, "description": "The current release media." }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "variant": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] } }, "purchase_base": { "properties": { "revoke_at": { "type": "integer", "nullable": true, "description": "Time at which the purchase should be revoked." } } }, "purchase_full_base": { "allOf": [ { "$ref": "#/components/schemas/purchase_base" }, { "properties": { "license_key": { "type": "string", "nullable": true, "description": "The key that will be used on the generated license from this purchase. (Only applicable when the purchase generates a license.)" }, "quantity": { "type": "integer", "description": "The quantity of products purchased." } } } ] }, "purchase_body": { "allOf": [ { "$ref": "#/components/schemas/purchase_full_base" }, { "properties": { "customer": { "type": "string", "description": "The UUID of the customer." }, "price": { "type": "string", "description": "The UUID of the price." }, "variant": { "type": "string", "description": "The UUID of the variant." } } } ] }, "purchase_update_body": { "allOf": [ { "$ref": "#/components/schemas/purchase_base" } ] }, "purchase_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/purchase_base" }, { "properties": { "live_mode": { "type": "boolean", "description": "Set to `true` if this purchase is in live mode, and set to `false` if it is in test mode." }, "revoked": { "type": "boolean", "description": "Whether or not this purchase is revoked." }, "revoked_at": { "type": "integer", "nullable": true, "description": "Time at which the purchase was revoked. Measured in seconds since the Unix epoch." }, "revoke_at": { "type": "integer", "nullable": true, "description": "Time at which the purchase should be revoked." }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "initial_order": { "nullable": true, "anyOf": [ { "type": "string", "description": "The first order that initiated this purchase.\n\n[Expandable](/api-reference/expanding-responses) – The associated order ID." }, { "$ref": "#/components/schemas/order_response", "description": "The first order that initiated this purchase.\n\n[Expanded](/api-reference/expanding-responses) – The associated order object." } ] }, "license": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated license ID." }, { "$ref": "#/components/schemas/license_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated license object." } ] }, "license_key": { "type": "string", "nullable": true, "description": "License key for subscriptions" }, "interpreted_downloads": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – The resolved downloads for this purchase. Returns variant downloads when the variant has downloads, falls back to product downloads otherwise." } ] }, "line_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated line item objects." } ] }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "subscription": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated subscription ID." }, { "$ref": "#/components/schemas/subscription_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated subscription object." } ] }, "variant": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] }, "review": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated review ID." }, { "$ref": "#/components/schemas/review_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated review object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "referral_base": { "properties": { "commission_amount": { "type": "integer", "description": "The amount in cents that will be paid out to the affiliate for this referral." }, "description": { "type": "string", "nullable": true, "description": "A brief description of what this referral is for." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this referral is in live mode, and set to `false` if it is in test mode." } } }, "referral_body": { "allOf": [ { "$ref": "#/components/schemas/referral_base" }, { "properties": { "affiliation": { "type": "string", "description": "The UUID of the affiliation." }, "checkout": { "type": "string", "description": "The UUID of the checkout." } } } ] }, "referral_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/referral_base" }, { "properties": { "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. If not set, this value will fallback to the default `Account` currency." }, "manual": { "type": "boolean", "description": "Whether or not this referral was created manually or automatically from a tracked click associated with a checkout." }, "status": { "type": "string", "description": "The status of the referral – one of `approved`, `canceled`, `denied`, `paid`, or `reviewing`." }, "refund_reduction_amount": { "type": "integer", "description": "The amount in cents that is reduced from the original commission amount due to refunds." }, "affiliation": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated affiliation ID." }, { "$ref": "#/components/schemas/affiliation_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated affiliation object." } ] }, "attributed_click": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated click ID." }, { "$ref": "#/components/schemas/click_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated click object." } ] }, "checkout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "payout": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payout ID." }, { "$ref": "#/components/schemas/payout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payout object." } ] }, "referral_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated referral item objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "referral_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "commission_amount": { "type": "integer", "description": "The amount in cents that will be paid out to the affiliate for this referral item." }, "line_item": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated line item ID." }, { "$ref": "#/components/schemas/line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated line item object." } ] }, "referral": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated referral ID." }, { "$ref": "#/components/schemas/referral_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated referral object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "refund_base": { "allOf": [ { "properties": { "amount": { "type": "integer", "description": "The amount in cents that was refunded, represented as a whole integer. For example `9900` is equivalent to `$99`." }, "reason": { "type": "string", "description": "The reason for this refund, which can be one of `duplicate`, `fraudulent`, `requested_by_customer`, or `expired_uncaptured_charge`." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "refund_body": { "allOf": [ { "$ref": "#/components/schemas/refund_base" }, { "properties": { "charge": { "type": "string", "description": "The UUID of the charge." }, "refund_items": { "type": "array", "description": "A list of this refund's items.", "items": { "$ref": "#/components/schemas/refund_item_body" } }, "return_request": { "type": "string", "description": "The UUID of the return request." } } } ] }, "refund_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/refund_base" }, { "properties": { "charge": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated charge ID." }, { "$ref": "#/components/schemas/charge_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated charge object." } ] }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase." }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "external_refund_id": { "type": "string", "description": "The external processor ID representing this refund." }, "failure_reason": { "type": "string", "nullable": true, "description": "The reason this refund failed, which can currently only be `insufficient_funds`." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this refund is in live mode, and set to `false` if it is in test mode." }, "refund_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated refund item objects." } ] }, "return_request": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated return request ID." }, { "$ref": "#/components/schemas/return_request_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated return request object." } ] }, "status": { "type": "string", "description": "The current status of this refund, which can be one of `pending`, `succeeded`, `failed`, or `canceled`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "refund_item_base": { "allOf": [ { "properties": { "restock": { "type": "boolean", "description": "Whether or not the associated line item should be restocked." }, "revoke_purchase": { "type": "boolean", "description": "Whether or not the associated purchase should be revoked." }, "quantity": { "type": "integer", "description": "The quantity of products being returned. This must be less than or equal to the fulfilled quantity of the associated line item." } } } ] }, "refund_item_body": { "allOf": [ { "$ref": "#/components/schemas/refund_item_base" }, { "properties": { "line_item": { "type": "string", "description": "The UUID of the line item." } } } ] }, "refund_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/refund_item_base" }, { "properties": { "line_item": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated line item ID." }, { "$ref": "#/components/schemas/line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated line item object." } ] }, "refund": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated refund ID." }, { "$ref": "#/components/schemas/refund_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated refund object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "return_item_base": { "allOf": [ { "properties": { "note": { "type": "string", "description": "A note to capture extra details about this return item. This is required when the return reason is `other`.", "nullable": true }, "return_reason": { "type": "string", "description": "The reason for returning the item – one of `color`, `defective`, `not_as_described`, `other`, `size_too_large`, `size_too_small`, `style`, `unknown`, `unwanted`, or `wrong_item`. The list of these reasons can be fetched from the `/return_reasons` endpoint.", "nullable": false }, "quantity": { "type": "integer", "description": "The quantity of products being returned. This must be less than or equal to the fulfilled quantity of the associated line item." } } } ] }, "return_item_body": { "allOf": [ { "$ref": "#/components/schemas/return_item_base" }, { "properties": { "line_item": { "type": "string", "description": "The UUID of the line item." } } } ] }, "return_item_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/return_item_base" }, { "properties": { "return_reason_description": { "type": "string", "description": "The full description of the return reason.", "nullable": false }, "return_request": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated return request ID." }, { "$ref": "#/components/schemas/return_request_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated return request object." } ] }, "line_item": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated line item ID." }, { "$ref": "#/components/schemas/line_item_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated line item object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "return_request_base": { "allOf": [ { "$ref": "#/components/schemas/model_metadata" } ] }, "return_request_body": { "allOf": [ { "$ref": "#/components/schemas/return_request_base" }, { "properties": { "order": { "type": "string", "description": "The UUID of the order." }, "return_items": { "type": "array", "description": "A list of this return request's items.", "items": { "$ref": "#/components/schemas/return_item_body" } } } } ] }, "return_request_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/return_request_base" }, { "properties": { "number": { "type": "string", "description": "The unique identifier for this return request that is auto generated based on this account's order protocol." }, "order": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated order ID." }, { "$ref": "#/components/schemas/order_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated order object." } ] }, "return_items": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated return item objects." } ] }, "status": { "type": "string", "description": "The current status of this return request – either `open` or `complete`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "review_base": { "allOf": [ { "properties": { "title": { "type": "string", "nullable": true, "description": "The title of the review." }, "body": { "type": "string", "nullable": true, "description": "The content/body of the review." }, "stars": { "type": "number", "format": "float", "nullable": true, "description": "The numerical rating provided in the review. Can be a decimal from 1.0 to 5.0." } } } ] }, "review_body": { "allOf": [ { "$ref": "#/components/schemas/review_base" }, { "properties": { "customer": { "type": "string", "description": "The UUID of the customer who wrote the review." }, "product": { "type": "string", "description": "The UUID of the product being reviewed." }, "purchase": { "type": "string", "nullable": true, "description": "The UUID of the purchase of product." } } } ] }, "review_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/review_base" }, { "properties": { "status": { "type": "string", "nullable": true, "description": "The status of the review (e.g. `in_review`, `published`, `unpublished`)." }, "verified": { "type": "boolean", "description": "Indicates whether the reviewer has purchased the product (based on presence of a purchase)." }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "purchase": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated purchase ID." }, { "$ref": "#/components/schemas/purchase_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated purchase object." } ] }, "review_medias": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated review media objects." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "review_media_base": { "allOf": [ { "properties": { "alt": { "type": "string", "nullable": true, "description": "The HTML alt attribute for the review media." }, "title": { "type": "string", "nullable": true, "description": "The HTML title attribute for the review media." }, "url": { "type": "string", "nullable": true, "description": "Instead of attaching a `Media` record, a public URL can be set. If set, this URL will be used to serve the review media asset." } } } ] }, "review_media_body": { "allOf": [ { "$ref": "#/components/schemas/review_media_base" }, { "properties": { "media": { "type": "string", "nullable": true, "description": "The UUID of the media." }, "review": { "type": "string", "description": "The UUID of the review." } } } ] }, "review_media_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/review_media_base" }, { "properties": { "media": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "review": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated review ID." }, { "$ref": "#/components/schemas/review_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated review object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "review_protocol_base": { "properties": { "reviews_enabled": { "type": "boolean", "description": "If set to `true`, reviews will be enabled globally for all products in the account. Individual products must also have reviews enabled for reviews to be shown." }, "solicit_reviews": { "type": "boolean", "description": "If set to `true`, review solicitation emails will be sent to customers who have purchased products. Individual products must also have solicitation enabled." }, "solicit_reviews_after_days": { "type": "integer", "description": "The number of days after an order is fulfilled that a review solicitation email will be sent to the customer." } } }, "review_protocol_body": { "allOf": [ { "$ref": "#/components/schemas/review_protocol_base" } ] }, "review_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/review_protocol_base" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "filter_body": { "description": "A rule tree describing how to filter records. May be a single `rule_condition` or a `rule_group` combining multiple conditions and nested groups with `and` / `or`. The valid `attribute_name` and `operator_label` values for each resource come from the corresponding `GET /v1//filter_schema` endpoint.\n", "oneOf": [ { "$ref": "#/components/schemas/rule_condition" }, { "$ref": "#/components/schemas/rule_group" } ], "example": { "type": "group", "combinator": "and", "conditions": [ { "type": "condition", "attribute_name": "order_type", "operator_label": "is", "comparison_value": "checkout" }, { "type": "condition", "attribute_name": "products.name", "operator_label": "contains", "comparison_value": "shirt" } ] } }, "rule_schema_attribute": { "properties": { "key": { "type": "string", "description": "The attribute key that can be used in rule conditions (e.g., `subtotal_amount`, `customer.created_at`)." }, "metadata": { "type": "boolean", "description": "Whether this attribute represents a metadata field." }, "supported_values": { "type": "array", "description": "A list of allowed values that can be used for comparison. Empty array if no specific values are enforced.", "items": { "type": "string" } }, "type": { "type": "string", "description": "The data type of the attribute. One of `string`, `numeric`, `date`, `uuid`, or `boolean`." }, "operators": { "type": "array", "description": "The list of comparison operators available for this attribute (e.g., `is`, `is_not`, `is_more_than`).", "items": { "type": "string" } } } }, "rule_schema_response": { "properties": { "object": { "type": "string", "description": "A string describing the object type returned." }, "schema_id": { "type": "string", "description": "The unique identifier for this rule schema (e.g., `auto_fee__checkout`, `auto_fee__line_item`)." }, "attributes": { "type": "array", "description": "The list of attributes available for building rule conditions.", "items": { "$ref": "#/components/schemas/rule_schema_attribute" } } } }, "list_response": { "type": "object", "properties": { "object": { "type": "string", "description": "A string describing the object type returned." }, "pagination": { "type": "object", "properties": { "count": { "type": "integer", "description": "The total number of items." }, "limit": { "type": "integer", "nullable": true, "description": "The number of items per page. The default is `20` and the maximum is `100`." }, "page": { "type": "integer", "nullable": true, "description": "The current page." } } }, "data": { "type": "array", "description": "An array of objects." } } }, "model_destroy_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "deleted": { "type": "boolean", "description": "Whether or not this object was succesfully deleted." } } } ] }, "model_identifiers": { "properties": { "id": { "type": "string", "nullable": true, "description": "The UUID of the specific object." }, "object": { "type": "string", "description": "A string describing the object type returned." } } }, "model_metadata": { "properties": { "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format." } } }, "model_timestamps": { "properties": { "created_at": { "type": "integer", "nullable": true, "description": "Time at which the object was created. Measured in seconds since the Unix epoch." }, "updated_at": { "type": "integer", "nullable": true, "description": "Time at which the object was last updated. Measured in seconds since the Unix epoch." } } }, "model_discarded_timestamp": { "properties": { "discarded_at": { "type": "integer", "nullable": true, "description": "Time at which the object was discarded. Measured in seconds since the Unix epoch." } } }, "stats_response": { "type": "object", "properties": { "object": { "type": "string", "description": "A string describing the object type returned." }, "query": { "type": "object", "properties": { "currency": { "type": "string", "nullable": true, "description": "The end of the date range for the query." }, "end_at": { "type": "integer", "description": "The end of the date range for the query." }, "interval": { "type": "string", "nullable": true, "description": "The interval that is set for the query." }, "start_at": { "type": "integer", "description": "The start of the date range for the query." } } }, "data": { "type": "array", "description": "An array of objects." } } }, "static_list_response": { "type": "object", "properties": { "object": { "type": "string", "description": "A string describing the object type returned." }, "data": { "type": "array", "description": "An array of objects." } } }, "shipment_base": { "properties": { "label_file_type": { "type": "string", "description": "The file type for the shipping label – one of `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PNG`, `ZPLII`." }, "parcel_template": { "type": "string", "nullable": true, "description": "The UUID of the parcel template." }, "weight": { "type": "string", "nullable": true, "description": "The weight of the parcel." }, "weight_unit": { "type": "string", "nullable": true, "description": "The unit of the weight – one of `g`, `kg`, `lb`, `oz`." }, "inherit_weight": { "type": "boolean", "description": "When true, inherit the weight from the fulfillment." }, "shipping_date": { "type": "integer", "description": "The date the shipment will be tendered to the carrier. Measured in seconds since the Unix epoch." }, "dimensions": { "type": "object", "nullable": true, "description": "The dimensions of the parcel.", "properties": { "length": { "type": "number", "description": "The length of the parcel." }, "width": { "type": "number", "description": "The width of the parcel." }, "height": { "type": "number", "description": "The height of the parcel." }, "unit": { "type": "string", "description": "The unit for dimensions – one of `in`, `cm`, `ft`, `m`, `mm`, `yd`." } } } } }, "shipment_body": { "allOf": [ { "$ref": "#/components/schemas/shipment_base" }, { "properties": { "fulfillment": { "type": "string", "description": "The UUID of the fulfillment." }, "shipping_provider": { "type": "string", "description": "The UUID of the shipping provider." }, "from_contact": { "description": "The origin contact for this shipment.", "allOf": [ { "$ref": "#/components/schemas/contact_body" } ] }, "to_contact": { "description": "The destination contact for this shipment.", "allOf": [ { "$ref": "#/components/schemas/contact_body" } ] } } } ] }, "shipment_purchase_body": { "properties": { "rate_id": { "type": "string", "description": "The ID of the selected rate to purchase." }, "label_file_type": { "type": "string", "description": "The file type for the shipping label – one of `PDF`, `PDF_A4`, `PDF_A6`, `PDF_4x6`, `PDF_4x8`, `PNG`, `ZPLII`." } } }, "shipment_rate": { "properties": { "id": { "type": "string", "description": "The unique identifier for this rate." }, "amount": { "type": "integer", "description": "The amount in cents to be paid for this rate. For example `9900` is equivalent to `$99`." }, "currency": { "type": "string", "description": "The three-letter currency code for this rate." }, "duration_terms": { "type": "string", "nullable": true, "description": "The clarification for the transit times." }, "estimated_days": { "type": "integer", "nullable": true, "description": "The estimated number of days for delivery." }, "provider": { "type": "string", "description": "The shipping carrier providing this rate." }, "provider_logo_url": { "type": "string", "description": "The URL for logo of the shipping carrier providing this rate.", "nullable": true }, "service_name": { "type": "string", "description": "The name of the shipping service." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "An array containing specific attributes of this rate in context of the entire shipment. one of `cheapest`, `fastest`, or `bestvalue`" } } }, "shipment_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipment_base" }, { "properties": { "status": { "type": "string", "description": "The current status of this shipment – one of `draft`, `quoted`, `purchased`, `voided`." }, "live_mode": { "type": "boolean", "description": "Whether or not this shipment was created in live mode." }, "label_url": { "type": "string", "nullable": true, "description": "The URL for the purchased shipping label." }, "tracking_number": { "type": "string", "nullable": true, "description": "The tracking number for this shipment." }, "tracking_url": { "type": "string", "nullable": true, "description": "The URL to track this shipment." }, "carrier": { "type": "string", "nullable": true, "description": "The shipping carrier for this shipment." }, "carrier_messages": { "type": "array", "nullable": true, "description": "Messages from carriers about this shipment.", "items": { "type": "object", "properties": { "carrier": { "type": "string", "description": "The carrier source of the messages." }, "messages": { "type": "array", "items": { "type": "string" }, "description": "The messages from this carrier." } } } }, "contact_validations": { "type": "object", "nullable": true, "description": "Contact validation results returned by the shipping provider. Only available after quoting.", "properties": { "from_contact": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the contact is valid." }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Validation messages for this contact." } } }, "to_contact": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the contact is valid." }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Validation messages for this contact." } } } } }, "tracking_status": { "type": "string", "nullable": true, "description": "The current tracking status – one of `unknown`, `pre_transit`, `in_transit`, `delivered`, `returned`, `failure`." }, "eta": { "type": "string", "nullable": true, "description": "The estimated time of arrival." }, "rates": { "type": "array", "description": "The available shipping rates for this shipment.", "items": { "$ref": "#/components/schemas/shipment_rate" } }, "selected_rate": { "allOf": [ { "$ref": "#/components/schemas/shipment_rate" } ], "nullable": true, "description": "The selected shipping rate for this shipment." }, "fulfillment": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated fulfillment ID." }, { "$ref": "#/components/schemas/fulfillment_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated fulfillment object." } ] }, "shipping_provider": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping provider ID." }, { "$ref": "#/components/schemas/shipping_provider_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping provider object." } ] }, "from_contact": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated contact ID." }, { "$ref": "#/components/schemas/contact_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated contact object." } ] }, "to_contact": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated contact ID." }, { "$ref": "#/components/schemas/contact_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated contact object." } ] }, "parcel_template": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated parcel template ID." }, { "$ref": "#/components/schemas/parcel_template_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated parcel template object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_choice_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "amount": { "type": "integer", "nullable": true, "description": "The amount in cents for this shipping choice. For example `9900` is equivalent to `$99`." }, "currency": { "type": "string", "nullable": true, "description": "The three-letter currency code for this shipping choice." }, "live": { "type": "boolean", "description": "Whether this shipping choice was quoted live from a carrier." }, "carrier_quotes": { "type": "array", "description": "The carrier quotes backing this shipping choice.", "items": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "external_rate_id": { "type": "string", "description": "The carrier's identifier for the quoted rate." }, "shipping_provider_id": { "type": "string", "description": "The UUID of the shipping provider that produced this quote." }, "rate": { "description": "The quoted carrier rate.", "allOf": [ { "$ref": "#/components/schemas/shipment_rate" } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] } }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] }, "shipping_method": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping method ID." }, { "$ref": "#/components/schemas/shipping_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping method object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_fee_base": { "properties": { "amount": { "type": "integer", "description": "The amount in cents to be added or subtracted, represented as an integer. For example `9900` is equivalent to `$99`." }, "description": { "type": "string", "description": "A short description of the shipping fee." } } }, "shipping_fee_body": { "allOf": [ { "$ref": "#/components/schemas/shipping_fee_base" }, { "properties": { "checkout": { "type": "string", "description": "The UUID of the checkout." } } } ] }, "shipping_fee_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_fee_base" }, { "properties": { "fee_type": { "type": "string", "description": "The type of shipping_fee – one of `auto` or `manual`." }, "checkout": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated checkout ID." }, { "$ref": "#/components/schemas/checkout_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated checkout object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_method_body": { "allOf": [ { "properties": { "name": { "type": "string", "description": "A name for this shipping method that will be visible to customers." }, "description": { "type": "string", "description": "A short description for this shipping method that will be visible to customers.", "nullable": true } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "shipping_method_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_method_body" }, { "properties": { "shipping_rates": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated shipping rate objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_profile_base": { "allOf": [ { "properties": { "name": { "type": "string", "description": "A name for this shipping profile that will be visible to customers." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "shipping_profile_body": { "allOf": [ { "$ref": "#/components/schemas/shipping_zone_base" }, { "properties": { "fallback_shipping_zone": { "type": "string", "nullable": true, "description": "The UUID of the shipping zone that should be the fallback when a specific shipping zone does not match the checkout's shipping address. This is commonly referred to as a \"Rest of World\" shipping zone." } } } ] }, "shipping_profile_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_profile_base" }, { "properties": { "default": { "type": "boolean", "description": "Whether or not this shipping profile is the default for the account." }, "fallback_shipping_zone": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping zone ID." }, { "$ref": "#/components/schemas/shipping_zone_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping zone object." } ] }, "products": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated product objects." } ] }, "shipping_zones": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated shipping zone objects." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_protocol_body": { "properties": { "shipping_enabled": { "type": "boolean", "description": "If set to `true` a shipping choice will be required for checkouts that have `shipping_enabled` products." } } }, "shipping_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_protocol_body" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "shipping_provider_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "approved": { "type": "boolean", "description": "Whether or not this shipping provider has been verified and approved." }, "enabled": { "type": "boolean", "description": "Whether or not this shipping provider is enabled." }, "live_mode": { "type": "boolean", "description": "Whether or not this shipping provider is in live mode." }, "provider_type": { "type": "string", "description": "The type of shipping provider – currently only `shippo`." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "carrier_account_response": { "type": "object", "properties": { "object": { "type": "string", "example": "carrier_account" }, "carrier": { "type": "string", "description": "The carrier token for this account (e.g. `usps`, `fedex`)." }, "carrier_name": { "type": "string", "description": "A human-readable name for the carrier (e.g. `USPS`, `FedEx`)." }, "service_levels": { "type": "array", "description": "The service levels offered by this carrier account.", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "The service level token (e.g. `usps_priority`). Use this to select a service level." }, "name": { "type": "string", "description": "A human-readable name for the service level (e.g. `Priority Mail`)." } } } } } }, "shipping_rate_amount_calculatable": { "type": "object", "required": [ "currency", "amount", "min_amount" ], "additionalProperties": false, "properties": { "currency": { "type": "string" }, "amount": { "type": "integer" }, "min_amount": { "type": "integer" }, "max_amount": { "type": "integer", "nullable": true } } }, "shipping_rate_flat_calculatable": { "type": "object", "required": [ "currency", "amount" ], "additionalProperties": false, "properties": { "currency": { "type": "string" }, "amount": { "type": "integer" } } }, "shipping_rate_weight_calculatable": { "type": "object", "required": [ "currency", "amount", "min_weight", "weight_unit" ], "additionalProperties": false, "properties": { "currency": { "type": "string" }, "amount": { "type": "integer" }, "min_weight": { "type": "number" }, "max_weight": { "type": "number", "nullable": true }, "weight_unit": { "type": "string", "enum": [ "lb", "oz", "kg", "g" ] } } }, "shipping_rate_live_calculatable": { "type": "object", "required": [ "currency", "shipping_provider_id", "service_tokens" ], "additionalProperties": false, "properties": { "currency": { "type": "string" }, "shipping_provider_id": { "type": "string" }, "service_tokens": { "type": "array", "items": { "type": "string" } }, "carrier_account": { "type": "string", "nullable": true }, "amount_handling": { "type": "integer", "nullable": true }, "percent_handling": { "type": "number", "nullable": true } } }, "shipping_rate_base": { "allOf": [ { "properties": { "calculatable_type": { "type": "string", "enum": [ "amount", "flat", "weight", "live" ], "description": "The kind of the nested calculatable." }, "calculatable": { "oneOf": [ { "$ref": "#/components/schemas/shipping_rate_amount_calculatable" }, { "$ref": "#/components/schemas/shipping_rate_flat_calculatable" }, { "$ref": "#/components/schemas/shipping_rate_weight_calculatable" }, { "$ref": "#/components/schemas/shipping_rate_live_calculatable" } ] } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "shipping_rate_body": { "allOf": [ { "$ref": "#/components/schemas/shipping_rate_base" }, { "properties": { "shipping_zone": { "type": "string", "description": "The UUID of the shipping zone." }, "shipping_method": { "type": "string", "description": "The UUID of the shipping method." } } } ] }, "shipping_rate_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_rate_base" }, { "$ref": "#/components/schemas/model_timestamps" }, { "properties": { "shipping_zone": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping zone ID." }, { "$ref": "#/components/schemas/shipping_zone_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping zone object." } ] }, "shipping_method": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping method ID." }, { "$ref": "#/components/schemas/shipping_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping method object." } ] } } } ] }, "shipping_zone_base": { "allOf": [ { "properties": { "name": { "type": "string", "description": "A name for this shipping zone that will be visible to customers." }, "postal_codes": { "type": "array", "description": "Optional array of postal code patterns to further filter addresses within the specified territories. Postal code filtering is applied in addition to territory filtering - an address must match both a territory and a postal code pattern (if provided) to be included in this shipping zone.\nSupports three matching modes:\n1. **Exact match**: Provide the complete postal code as a string (e.g., \"90210\", \"SW1A 1AA\").\n2. **Range match**: Use three dots (\"...\") to specify a numeric range (e.g., \"90210...99000\" matches all postal codes from 90210 to 99000). Only numeric postal codes are supported for ranges.\n3. **Wildcard match**: Use asterisk (\"*\") for prefix matching (e.g., \"902*\" matches \"90210\", \"90211\", \"902AB\", etc.).\nAll postal codes are normalized (uppercased and trimmed) before matching. If the array is empty, no postal code filtering is applied and all addresses within the territories will match.", "items": { "type": "string" } }, "territories": { "type": "array", "description": "The specific territories that this shipping zone covers.", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "The country associated with the territory." }, "states": { "type": "array", "description": "List of states within the country.", "items": { "type": "string" } } } } } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "shipping_zone_body": { "allOf": [ { "$ref": "#/components/schemas/shipping_zone_base" }, { "properties": { "shipping_profile": { "type": "string", "description": "The UUID of the shipping profile." } } } ] }, "shipping_zone_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/shipping_zone_base" }, { "$ref": "#/components/schemas/model_timestamps" }, { "properties": { "shipping_profile": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping profile ID." }, { "$ref": "#/components/schemas/shipping_profile_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping profile object." } ] }, "shipping_rates": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated shipping rate objects." } ] } } } ] }, "subscription_base": { "allOf": [ { "properties": { "ad_hoc_amount": { "type": "integer", "nullable": true, "description": "The amount to use for this subscription when the associated price is `ad_hoc=true`." }, "affiliation_expires_at": { "type": "integer", "nullable": true, "description": "Time at which the affiliation will expire." }, "cancel_at_period_end": { "type": "boolean", "description": "If the subscription is set to cancel at the end of the current period. You can use this attribute to determine whether a subscription that has a `status` of `active` is scheduled to be canceled at the end of the current period." }, "live_mode": { "type": "boolean", "description": "Set to `true` if this subscription is in live mode, and set to `false` if it is in test mode." }, "manual_payment": { "type": "boolean", "description": "Whether or not this subscription should finalize checkouts during renewal with the `manual_payment=true` option." }, "quantity": { "type": "integer", "description": "The quantity of products being purchased." }, "restore_at": { "type": "integer", "nullable": true, "description": "The time at which this subscription will automatically be restored. This can only be set if the subscription is canceled or set to cancel at period end." }, "restart_on_completed": { "type": "boolean", "description": "Whether installment subscriptions should be automatically restarted when they reach the completed state. When the subscription is created, this value will be inherited from the price `restart_subscription_on_completed` value." }, "tax_enabled": { "type": "boolean", "description": "Whether or not tax is enabled for this subscription. This will default to the account's `tax_protocol.tax_enabled` value when the subscription is created." }, "trial_end_at": { "type": "integer", "nullable": true, "description": "If the subscription has a trial, the end of that trial." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "subscription_body": { "allOf": [ { "$ref": "#/components/schemas/subscription_base" }, { "properties": { "affiliation": { "type": "string", "description": "The affiliation associated with this subscription." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This value will match the `Account` currency." }, "customer": { "type": "string", "description": "The UUID of the customer." }, "discount": { "description": "The parameters of the discount to be applied to this subscription.", "allOf": [ { "$ref": "#/components/schemas/discount_body" } ] }, "imported": { "type": "boolean", "description": "Whether or not this subscription is being imported from another platform. If `true`, the `first_sc_period_start_at` value must be set." }, "manual_payment_method": { "type": "string", "description": "The UUID of the manual payment method." }, "first_sc_period_start_at": { "type": "integer", "nullable": true, "description": "The time at which the next period should start for this subscription. This value should be set when importing subscriptions to maintain the billing cycle. (This value is only applicable during subscription creation.)" }, "payment_method": { "type": "string", "description": "The UUID of the payment method." }, "price": { "type": "string", "description": "The UUID of the price." }, "purge_pending_update": { "type": "boolean", "description": "When set to `true` the `pending_update` will be cleared." }, "shipping_method": { "type": "string", "nullable": true, "description": "The UUID of the shipping method." }, "variant": { "type": "string", "description": "The UUID of the variant." } } } ] }, "subscription_cancel_body": { "properties": { "restore_at": { "type": "integer", "nullable": true, "description": "The time at which this subscription will automatically be restored. This can only be set if the subscription is canceled or set to cancel at period end." } } }, "subscription_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/subscription_base" }, { "properties": { "current_period_end_at": { "type": "integer", "nullable": true, "description": "End of the current period that the subscription is in. At the end of this period, a new period will be created. This will be `null` when the subscription has a one-time price." }, "current_period_start_at": { "type": "integer", "nullable": true, "description": "Start of the current period that the subscription is in." }, "ended_at": { "type": "integer", "nullable": true, "description": "If the subscription has ended, the date the subscription ended." }, "finite": { "type": "boolean", "description": "Whether or not this subscription belongs to a price with a set `recurring_period_count`, meaning it has a defined end." }, "last_renewal_reminder_sent_at": { "type": "integer", "nullable": true, "description": "Time at which the last renewal reminder notification sent. Measured in seconds since the Unix epoch." }, "pending_update": { "type": "object", "properties": { "price": { "type": "string", "description": "The UUID of the price this subscription will be updated to at the end of the current period." }, "quantity": { "type": "integer", "description": "The quantity of products being purchased at the end of the current period." } } }, "portal_url": { "type": "string", "nullable": true, "description": "A URL that will redirect to this subscription's correct portal page (hosted or external)." }, "price_readonly": { "type": "boolean", "description": "Whether or not the price of this subscription can be modified. If `true`, the price is locked and cannot be changed" }, "remaining_period_count": { "type": "integer", "nullable": true, "description": "The number of periods remaining before this subscription ends. This count is reduced when a period is paid." }, "subtotal_amount": { "type": "integer", "description": "Total of the subscription before discounts or taxes are applied." }, "status": { "type": "string", "description": "The current status of this subscription, which can be one of `incomplete`, `trialing`, `active`, `past_due`, `canceled`, or `completed`." }, "affiliation": { "type": "object", "nullable": true, "description": "The affiliation associated with this subscription." }, "current_cancellation_act": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated cancellation act ID." }, { "$ref": "#/components/schemas/cancellation_act_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated cancellation act object." } ] }, "current_period": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated period ID." }, { "$ref": "#/components/schemas/period_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated period object." } ] }, "customer": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated customer ID." }, { "$ref": "#/components/schemas/customer_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated customer object." } ] }, "discount": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated discount ID." }, { "$ref": "#/components/schemas/discount_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated discount object." } ] }, "manual_payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated manual payment method ID." }, { "$ref": "#/components/schemas/manual_payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated manual payment method object." } ] }, "payment_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated payment method ID." }, { "$ref": "#/components/schemas/payment_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated payment method object." } ] }, "periods": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated period objects." } ] }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "purchase": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated purchase ID." }, { "$ref": "#/components/schemas/purchase_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated purchase object." } ] }, "shipping_method": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated shipping method ID." }, { "$ref": "#/components/schemas/shipping_method_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated shipping method object." } ] }, "variant": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated variant ID." }, { "$ref": "#/components/schemas/variant_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated variant object." } ] }, "variant_options": { "type": "array", "nullable": true, "description": "An array of the associated variant's options." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "subscription_protocol_body": { "properties": { "bypass_duplicate_trials": { "type": "boolean", "description": "Whether or not to skip the trial period for a product if the customer has already been in a trial." }, "cancel_behavior": { "type": "string", "description": "Controls how subscription cancellations should be handled – one of `immediate` or `pending`." }, "cancel_window_enabled": { "type": "boolean", "description": "Whether or not the subscription cancel window is enabled." }, "cancel_window_days": { "type": "integer", "description": "The number of days prior to a subscription renewing that the cancel option will be visible to customers." }, "default_payment_method_detach_enabled": { "type": "boolean", "description": "Whether or not default payment methods can be removed." }, "default_payment_method_fallback_enabled": { "type": "boolean", "description": "Whether or not the customer's default payment method should be used as a fallback when a subscription does not have a payment method." }, "downgrade_behavior": { "type": "string", "description": "Controls how subscription changes should be handled when downgrading – one of `immediate` or `pending`." }, "payment_retry_window_weeks": { "type": "integer", "description": "The number of weeks to retry failed subscription payments before canceling the subscription." }, "preservation_enabled": { "type": "boolean", "description": "Whether or not subscription preservation is enabled." }, "preservation_locales": { "type": "object", "description": "A collection of locale strings that will be used when displaying the subscription preservation flow to customers. These strings have access to the following liquid variables: `amount` and `name`." }, "remind_at_period_percent_remaining": { "type": "number", "description": "Specifies the percentage of time remaining in the subscription period at which a reminder should be sent. For example, if set to 25%, the reminder will be triggered when there is 25% of the subscription period remaining." }, "remind_after_days": { "type": "integer", "nullable": true, "description": "Specifies the minimum number of days that must pass since the last reminder (or subscription creation if no reminder has been sent) before a new reminder can be sent. For example, if set to 180, a reminder will only be sent if at least 180 days have passed since the last reminder. This prevents reminders from being sent too frequently across multiple subscription periods." }, "reschedule_existing_reminders": { "type": "boolean", "nullable": true, "default": false, "description": "Whether or not existing subscription reminders should be recalculated. Only applicable when `remind_at_period_percent_remaining` or `remind_after_days` are changed." }, "require_upfront_payment_method": { "type": "boolean", "description": "Whether or not a payment method should be required for subscriptions that have an initial period amount of $0 (free trial or coupon)." }, "revoke_purchases_on_past_due": { "type": "boolean", "description": "Whether or not a purchase should be revoked when a subscription becomes past_due. If the subscription transitions to the `active` or `trialing` state the associated purchase will be automatically invoked again." }, "upgrade_behavior": { "type": "string", "description": "Controls how subscription changes should be handled when upgrading – one of `immediate` or `pending`." } } }, "subscription_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/subscription_protocol_body" }, { "properties": { "preservation_coupon": { "anyOf": [ { "type": "string", "description": "The coupon that is applied to subscriptions when a cancellation reason with `coupon_enabled=true` is selected and the susbcription is preserved.\n\n[Expandable](/api-reference/expanding-responses) – The associated preservation coupon ID." }, { "$ref": "#/components/schemas/preservation_coupon_response", "description": "The coupon that is applied to subscriptions when a cancellation reason with `coupon_enabled=true` is selected and the susbcription is preserved.\n\n[Expanded](/api-reference/expanding-responses) – The associated preservation coupon object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "swap_base": { "allOf": [ { "properties": { "archived": { "type": "boolean", "description": "Whether or not this swap is archived." }, "description": { "type": "string", "nullable": true, "description": "A description of this swap. This text will be visibile to customers in the checkout summary when offered the swap." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "swap_body": { "allOf": [ { "$ref": "#/components/schemas/swap_base" }, { "properties": { "price": { "type": "string", "description": "The UUID of the price to swap from." }, "swap_price": { "type": "string", "description": "The UUID of the price to swap to." } } } ] }, "swap_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/swap_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "swap_price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tax_identifier_body": { "properties": { "number": { "type": "string", "nullable": true, "description": "The tax ID number." }, "number_type": { "type": "string", "description": "The type of tax ID number." } } }, "tax_identifier_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/tax_identifier_body" }, { "properties": { "eu_vat_verified": { "type": "boolean", "description": "Whether or not this a verified EU VAT number based on regex validation and an attempted VIES check." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tax_override_body": { "properties": { "shipping": { "type": "boolean", "description": "Whether or not this tax override applies to shipping." }, "rate": { "type": "number", "nullable": true, "description": "The tax rate to use for this tax override." }, "product_collection": { "type": "string", "description": "The UUID of the product collection. (Not required if `shipping=true`.)" }, "tax_zone": { "type": "string", "description": "The UUID of the tax zone." } } }, "tax_override_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/tax_override_body" }, { "properties": { "product_collection": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product collection ID." }, { "$ref": "#/components/schemas/product_collection_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product collection object." } ] }, "tax_zone": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax zone ID." }, { "$ref": "#/components/schemas/tax_zone_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax zone object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tax_protocol_base": { "properties": { "ca_tax_enabled": { "type": "boolean", "description": "If set to `true` GST taxes will be calculated for all Canadian provinces." }, "default_rate": { "type": "number", "nullable": true, "description": "The default tax rate to use for checkouts when a specific `tax_registration` is not found. This will only apply if `default_tax_enabled=true`." }, "default_tax_enabled": { "type": "boolean", "description": "Whether or not to use the `default_rate` when a specific `tax_registration` is not found." }, "eu_micro_exemption_enabled": { "type": "boolean", "description": "If set to `true` VAT taxes will be calculated using the account's home country VAT rate." }, "eu_tax_enabled": { "type": "boolean", "description": "If set to `true` VAT taxes will be calculated for all EU countries." }, "tax_behavior": { "type": "string", "description": "Determines how taxes will be calculated. One of `exclusive` or `inclusive`." }, "tax_enabled": { "type": "boolean", "description": "If set to `true` taxes will be automatically calculated." }, "eu_vat_required": { "type": "boolean", "description": "Whether or not an `eu_vat` tax identifier is required when a customer's address is in the EU." }, "eu_vat_unverified_behavior": { "type": "string", "description": "Determines how `eu_vat` tax identifiers will be handled when they are not verified against VIES. One of `apply_reverse_charge`, `error`, or `skip_reverse_charge`." }, "eu_vat_local_reverse_charge": { "type": "boolean", "description": "Whether or not reverse charge should be applied when the customer's address is in the same country as the tax protocol address." } } }, "tax_protocol_body": { "allOf": [ { "$ref": "#/components/schemas/tax_protocol_base" }, { "properties": { "address": { "description": "The associated address used for tax calculations.", "allOf": [ { "$ref": "#/components/schemas/address_body" } ] }, "ca_tax_identifier": { "description": "The tax identifier to be used for all Canadian provinces.", "allOf": [ { "$ref": "#/components/schemas/tax_identifier_body" } ] }, "eu_tax_identifier": { "description": "The tax identifier to be used for all EU countries.", "allOf": [ { "$ref": "#/components/schemas/tax_identifier_body" } ] } } } ] }, "tax_protocol_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/tax_protocol_base" }, { "properties": { "address": { "nullable": true, "anyOf": [ { "type": "string", "description": "The address used for tax calculations.\n\n[Expandable](/api-reference/expanding-responses) – The associated address ID." }, { "$ref": "#/components/schemas/address_response", "description": "The address used for tax calculations.\n\n[Expanded](/api-reference/expanding-responses) – The associated address object." } ] }, "ca_tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "The Canadian tax identifier.\n\n[Expandable](/api-reference/expanding-responses) – The associated ca tax identifier ID." }, { "$ref": "#/components/schemas/ca_tax_identifier_response", "description": "The Canadian tax identifier.\n\n[Expanded](/api-reference/expanding-responses) – The associated ca tax identifier object." } ] }, "eu_tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "The EU tax identifier.\n\n[Expandable](/api-reference/expanding-responses) – The associated eu tax identifier ID." }, { "$ref": "#/components/schemas/eu_tax_identifier_response", "description": "The EU tax identifier.\n\n[Expanded](/api-reference/expanding-responses) – The associated eu tax identifier object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tax_registration_body": { "properties": { "label": { "type": "string", "nullable": true, "description": "The tax label for this tax registration. If blank, the default tax label from the tax zone will be used." }, "manual_rate": { "type": "number", "nullable": true, "description": "The manual tax rate to use for this tax registration." }, "tax_identifier": { "description": "The tax identifier to set for this tax registration.", "allOf": [ { "$ref": "#/components/schemas/tax_identifier_body" } ] }, "tax_zone": { "type": "string", "description": "The UUID of the tax zone." } } }, "tax_registration_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/tax_registration_body" }, { "properties": { "tax_identifier": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax identifier ID." }, { "$ref": "#/components/schemas/tax_identifier_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax identifier object." } ] }, "tax_zone": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated tax zone ID." }, { "$ref": "#/components/schemas/tax_zone_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated tax zone object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tax_zone_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "country": { "type": "string", "description": "The two-letter code of the country - ISO 3166-1. (Reference the Atlas API for all available codes.)" }, "country_name": { "type": "string", "description": "The full country name." }, "default_rate": { "type": "number", "description": "The default tax rate for the tax zone." }, "default_label": { "type": "string", "description": "The label used to describe the default tax rate." }, "manual": { "type": "boolean", "description": "Whether or not tax registrations for this zone require a `manual_rate`." }, "region": { "type": "string", "description": "The tax region this zone is in." }, "state": { "type": "string", "description": "The code of the state - ISO 3166-2. (Reference the Atlas API for all available codes.)" }, "state_name": { "type": "string", "description": "The full state/province name." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "tracking_body": { "allOf": [ { "properties": { "number": { "type": "string", "description": "The tracking number provided by the courier." }, "url": { "type": "string", "nullable": true, "description": "The URL to track this shipment on the courier's website. (This is inferred from the tracking number for some couriers.)" } } } ] }, "tracking_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/tracking_body" }, { "properties": { "courier_name": { "type": "string", "nullable": true, "description": "The name of the courier for this shipment. (This is inferred from the tracking number for some couriers.)" }, "fulfillment": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated fulfillment ID." }, { "$ref": "#/components/schemas/fulfillment_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated fulfillment object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "upsell_base": { "allOf": [ { "properties": { "amount_off": { "type": "integer", "nullable": true, "description": "Amount (in the `currency` of the price) that will be taken off line items associated with this upsell." }, "duplicate_purchase_behavior": { "type": "string", "description": "How to handle duplicate purchases of the product – can be one of `allow`, `block_within_checkout`, or `block`." }, "fee_description": { "type": "string", "description": "The description for this upsell which will be visible to customers." }, "percent_off": { "type": "number", "nullable": true, "description": "Percent that will be taken off line items associated with this upsell." }, "replacement_behavior": { "type": "string", "description": "Whether or not to replace line items in the associated checkout. Replacement occurs when a line item is upsold. Possible values include:\n- `none` (default): No line items will be replaced.\n- `all`: All line items will be replaced.\n" }, "step": { "type": "string", "description": "Where this upsell falls in position within the upsell funnel – can be one of `initial`, `accepted`, or `declined`." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "upsell_body": { "allOf": [ { "$ref": "#/components/schemas/upsell_base" }, { "properties": { "price": { "type": "string", "description": "The UUID of the price." }, "upsell_funnel": { "type": "string", "description": "The UUID of the upsell funnel." } } } ] }, "upsell_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/upsell_base" }, { "properties": { "price": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated price ID." }, { "$ref": "#/components/schemas/price_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated price object." } ] }, "upsell_funnel": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated upsell funnel ID." }, { "$ref": "#/components/schemas/upsell_funnel_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated upsell funnel object." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "upsell_funnel_base": { "allOf": [ { "properties": { "archived": { "type": "boolean", "description": "Whether or not this upsell funnel is archived." }, "enabled": { "type": "boolean", "description": "Whether or not this upsell funnel is enabled." }, "filter_match_type": { "type": "string", "nullable": true, "description": "The matching strategy to use when filtering upsell funnels – can be `null` or one of `all`, `any`, `none`. If `null`, the upsell funnel will not be filtered and will be applicable to all checkouts." }, "filter_price_ids": { "type": "array", "description": "The prices to filter this upsell funnel by." }, "filter_product_ids": { "type": "array", "description": "The products to filter this upsell funnel by." }, "name": { "type": "string", "nullable": true, "description": "A name for this upsell that will be visible to customers." }, "priority": { "type": "integer", "description": "The priority of this upsell in relation to other upsells. Must be in the range of `1` - `5` with `5` being the highest priority and `1` being the lowest." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "upsell_funnel_body": { "allOf": [ { "$ref": "#/components/schemas/upsell_funnel_base" } ] }, "upsell_funnel_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/upsell_funnel_base" }, { "properties": { "archived_at": { "type": "integer", "nullable": true, "description": "Time at which the object was archived. Measured in seconds since the Unix epoch." }, "upsells": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – Property not returned unless expanded." }, { "$ref": "#/components/schemas/list_response", "description": "[Expanded](/api-reference/expanding-responses) – A list of associated upsell objects." } ] } } }, { "$ref": "#/components/schemas/model_discarded_timestamp" }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "user_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "email": { "type": "string", "description": "The email address of the user." }, "first_name": { "type": "string", "description": "The first name of the user." }, "last_name": { "type": "string", "description": "The last name of the user." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "variant_base": { "allOf": [ { "properties": { "amount": { "type": "integer", "nullable": true, "description": "The amount in cents to be charged, represented as a whole integer for this specific integer. If empty, the regular `Price` amount will be used. If the `Product` has multiple prices, then this amount will be ignored and the selected `Price` amount will be used." }, "allow_out_of_stock_purchases": { "type": "boolean", "nullable": true, "description": "Whether or not to allow purchases of this variant when stock runs out. If true, the stock levels for this variant can go below zero. If `null`, inherits from the product." }, "auto_fulfill_enabled": { "type": "boolean", "nullable": true, "description": "Whether or not this variant should be auto fulfilled when it is purchased. This can only be `true` when `shipping_enabled` is `false`. If `null`, inherits from the product." }, "dimensions": { "type": "object", "nullable": true, "description": "The physical dimensions of this variant. If `null`, inherits from the product.", "properties": { "length": { "type": "number", "description": "The length dimension." }, "width": { "type": "number", "description": "The width dimension." }, "height": { "type": "number", "description": "The height dimension." }, "unit": { "type": "string", "description": "The unit of measurement – one of `cm`, `mm`, `m`, `in`, `ft`." } } }, "downloads_enabled": { "type": "boolean", "nullable": true, "description": "Whether or not downloads are enabled for this variant. When `false`, downloads will be disabled for this variant. When `true`, the downloads that are set for this variant will override the product downloads. If no downloads are set, then the product downloads will be used." }, "license_activation_limit": { "type": "integer", "nullable": true, "description": "The max number of activations allowed per license. If `null`, inherits from the product or price." }, "option_1": { "type": "string", "description": "The value for the first variant option." }, "option_2": { "type": "string", "nullable": true, "description": "The value for the second variant option." }, "option_3": { "type": "string", "nullable": true, "description": "The value for the third variant option." }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this variant when displayed to customers." }, "purchase_limit": { "type": "integer", "nullable": true, "description": "The max number of times this variant can be purchased by a customer. If `null`, inherits from the product." }, "shipping_enabled": { "type": "boolean", "nullable": true, "description": "If set to `true` checkouts with this variant will require a full shipping address. If `null`, inherits from the product." }, "sku": { "type": "string", "nullable": true, "description": "The stock keeping unit for this variant." }, "stock_enabled": { "type": "boolean", "nullable": true, "description": "Whether or not stock will be tracked for this variant. If `null`, inherits from the product." }, "tax_category": { "type": "string", "nullable": true, "description": "The tax category/code that matches this variant. If `null`, inherits from the product." }, "tax_enabled": { "type": "boolean", "nullable": true, "description": "If set to `true`, this variant is considered taxable. If `null`, inherits from the product." }, "weight": { "type": "number", "nullable": true, "description": "The variant weight, meant to be displayable to the customer. If `null`, inherits from the product." }, "weight_unit": { "type": "string", "nullable": true, "description": "The weight unit for this variant. If `null`, inherits from the product." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "variant_body": { "allOf": [ { "$ref": "#/components/schemas/variant_base" }, { "properties": { "current_release_download": { "type": "string", "description": "The UUID of the current release download." }, "image": { "type": "string", "description": "The UUID of the media." }, "product": { "type": "string", "description": "The UUID of the product." }, "stock_adjustment": { "type": "integer", "description": "The amount to adjust the stock by. This can be a positive or negative number." } } } ] }, "variant_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/variant_base" }, { "properties": { "available_stock": { "type": "integer", "description": "The total amount of stock available for purchase. This is the total `stock` on hand minus `held_stock`." }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in lowercase. This is inherited from the price." }, "current_release_download": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated download ID." }, { "$ref": "#/components/schemas/download_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated download object." } ] }, "current_version": { "type": "boolean", "description": "Whether or not this object represents the current version of this variant. (This will be `false` if the association was created to this variant before it was altered. In this case, we will lookup the version of the variant at the time it was associated.)" }, "held_stock": { "type": "integer", "description": "The total amount of stock being held by unfulfilled line items." }, "image": { "nullable": true, "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated media ID." }, { "$ref": "#/components/schemas/media_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated media object." } ] }, "option_names": { "type": "array", "description": "An array of the associated product's variant option names." }, "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "stock": { "type": "integer", "description": "The total amount of stock on hand for this product." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "variant_option_body": { "allOf": [ { "properties": { "display_type": { "type": "string", "description": "The display type of the variant option – one of \"radio\" or \"dropdown\"." }, "name": { "type": "string", "description": "The variant option's name – i.e. Size, Color, etc." }, "position": { "type": "integer", "nullable": true, "description": "The ordering position of this variant option when displayed to customers." } } }, { "$ref": "#/components/schemas/model_metadata" } ] }, "variant_option_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/variant_option_body" }, { "properties": { "product": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated product ID." }, { "$ref": "#/components/schemas/product_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated product object." } ] }, "values": { "type": "array", "description": "A list of values for this variant option. (These are inferred from the values set on variants.)" } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "verification_code_body": { "properties": { "email": { "type": "string", "description": "The email to send the verification code to." } } }, "verification_code_verify_body": { "properties": { "code": { "type": "string", "description": "The code that was sent to the email." }, "email": { "type": "string", "description": "The email the verification code was sent to." } } }, "verification_code_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "properties": { "email": { "type": "string", "description": "The email the verification code was sent to." }, "verified": { "type": "boolean", "description": "Whether or not this verification code has been verified." }, "verified_at": { "type": "integer", "nullable": true, "description": "Date when the verification code was verified." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "warehouse_base": { "properties": { "label": { "type": "string", "description": "The label for this warehouse." }, "default": { "type": "boolean", "description": "Whether or not this warehouse is the account's default." } } }, "warehouse_body": { "allOf": [ { "$ref": "#/components/schemas/warehouse_base" }, { "properties": { "contact": { "description": "The contact for this warehouse.", "allOf": [ { "$ref": "#/components/schemas/contact_body" } ] } } } ] }, "warehouse_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/warehouse_base" }, { "properties": { "contact": { "anyOf": [ { "type": "string", "description": "[Expandable](/api-reference/expanding-responses) – The associated contact ID." }, { "$ref": "#/components/schemas/contact_response", "description": "[Expanded](/api-reference/expanding-responses) – The associated contact object." } ] } } }, { "$ref": "#/components/schemas/model_timestamps" } ] }, "webhook_endpoint_body": { "properties": { "description": { "type": "string", "nullable": true, "description": "An optional description of what this webhook endpoint is used for." }, "enabled": { "type": "boolean", "description": "Whether or not this webhook endpoint is active." }, "url": { "type": "string", "description": "The URL of this webhook endpoint." }, "webhook_events": { "type": "array", "description": "The webhook events that this webhook endpoint should send webhooks for. For example, if `webhook_events=[\"order.created\"]` then the webhook endpoint will only send webhooks when the `order.created` event occurs.", "items": { "type": "string" } } } }, "webhook_endpoint_response": { "allOf": [ { "$ref": "#/components/schemas/model_identifiers" }, { "$ref": "#/components/schemas/webhook_endpoint_body" }, { "properties": { "automation_service": { "type": "string", "nullable": true, "description": "The automation service that this webhook endpoint is pointed at. One of `suretriggers` or `zapier`." }, "erroring_grace_period_ends_at": { "type": "integer", "nullable": true, "description": "The time at which this webhook endpoint will be disabled if it continues to error." }, "erroring_grace_period_started_at": { "type": "integer", "nullable": true, "description": "The time at which this webhook endpoint started erroring. A webhook endpoint is considered to be erroring when it returns a non 2xx response code. After 3 days, with 40% or more of requests erroring, the webhook endpoint will be disabled." }, "signing_secret": { "type": "string", "description": "The webhook endpoint’s signing secret, used to generate webhook signatures." } } }, { "$ref": "#/components/schemas/model_timestamps" } ] } } }, "tags": [ { "name": "Abandonded Checkouts", "description": "An abandonded checkout represents a customer's most recent incomplete checkout.\nWhen a checkout is associated with a customer and is left unpaid for 30 minutes a corresponding abandoned checkout is created. Only one abandoned checkout will be created per customer every 10 days." }, { "name": "Abandoned Checkout Protocols", "description": "An abandoned checkout protocol represents the abandoned checkout settings for an account." }, { "name": "Accounts", "description": "This is an object representing a SureCart account. You can retrieve it to see properties on the account like it's current - name or default currency." }, { "name": "Activations", "description": "An activation represents a single use of a license." }, { "name": "Affiliation Products", "description": "An affiliation product allows for setting a specific commission structure for a product and affiliation." }, { "name": "Affiliation Protocols", "description": "An affiliation protocol represents the affiliate settings for an account." }, { "name": "Affiliation Requests", "description": "An affiliation request represents a request from an affiliate to join an account's affiliate program." }, { "name": "Affiliations", "description": "An affiliation represents a relationship between an affiliate and an account." }, { "name": "Balance Transactions", "description": "You may modify a customer's balance by creating a balance transaction, which increments or decrements the customer's balance by the specified amount." }, { "name": "Balances", "description": "Each customer has a balance value for each currency, which denotes a debit or credit that's automatically applied to their next invoice upon finalizing." }, { "name": "Brands", "description": "A brand represents the design and branding settings for an account." }, { "name": "Bulk Actions", "description": "A bulk action is a way to perform a single action on multiple resources at once." }, { "name": "Bumps", "description": "A bump represents a price that will be conditionally recommended to customers during checkout. Bumps are displayed below the checkout summary and offer an easy way to add additional products to the checkout. They are a more powerful alternative to swaps, but they are more intrusive to the checkout experience." }, { "name": "Cancellation Acts", "description": "A cancellation act represents a customer attempt to cancel a subscription." }, { "name": "Cancellation Reasons", "description": "Cancellation reasons are specific reasons that a customer can select from when cancelling a subscription." }, { "name": "Charges", "description": "A Charge represents a credit or debit card transaction that was captured through one of your processors. Only succesfully captured charges are recorded in SureCart." }, { "name": "Checkouts", "description": "A checkout represents a collection of one-time and/or subscription products that a customer intends to purchase." }, { "name": "Checkout Portal Protocols", "description": "A checkout portal protocol represents the checkout portal settings for an account." }, { "name": "Clicks", "description": "A click is a record of a customer clicking on an affiliate link. Click records are associated with checkouts to create referrals." }, { "name": "Coupons", "description": "A coupon contains information about a percent-off or amount-off discount.\nThe coupon object can be used to discount either one-time payments or subscriptions. There are some additional parameters that apply to subscriptions, but are not applicable to one-time payments, such as duration. Regardless of what duration is set to, it only applies once for one-time payments." }, { "name": "Customer Links", "description": "Customer links are temporary objects that allow access to customers through email lookup.\nEach customer link is valid for the greater of 1 hour after it's `created_at` time or 1 hour after it's `first_used_at` time. This means that if a customer link is not used within the first hour it expires. If a customer link is used within the first hour then it is valid for another hour starting from the time it was first used. So, a customer link that is used 30min after it's created will be valid for a total of 1hr 30min." }, { "name": "Customer Notification Protocols", "description": "A customer notification protocol represents the customer notification settings for an account." }, { "name": "Customers", "description": "Customer objects allow you to perform recurring charges, and to track multiple charges, that are associated with the same customer." }, { "name": "Customer Portal Protocols", "description": "A customer portal protocol represents the customer portal settings for an account." }, { "name": "Display Currencies", "description": "Display currencies are the currencies that are available to customers from the currency selector on your store." }, { "name": "Downloads", "description": "Downloads represent the medias that can be downloaded when a specific product is purchased." }, { "name": "Events", "description": "Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new `Event` object. For example, when a subscription updates, we create a `subscription.updated` event." }, { "name": "Exports", "description": "Exports allow you to download your raw data from your SureCart account." }, { "name": "Fees", "description": "A fee represents an additional amount added or subtracted from a specific line item." }, { "name": "Fulfillment Items", "description": "A fulfillment item represents a specific line item being shipped to a customer within a fulfillment." }, { "name": "Fulfillments", "description": "A fulfillment represents a shipment of products within an order to a customer." }, { "name": "Imports", "description": "Imports allow you to upload raw data into your SureCart account to batch create customers, products, subscriptions, etc." }, { "name": "Invoices", "description": "Invoices are statements of amounts owed by a customer. They wrap a checkout and can be configured to collect payment automatically or be sent to the customer for payment." }, { "name": "Licenses", "description": "A license represents permission for a customer to use a specific product. Each license has an auto-generated `key` which can be used with the public license endpoints." }, { "name": "Line Items", "description": "A line item represents a price and it's quantity being purchased by a customer within a checkout." }, { "name": "Manual Charges", "description": "A manual charge represents record of a payment that was captured outside of SureCart." }, { "name": "Manual Payment Methods", "description": "Manual payment methods are used to allow customers to checkout with manual approval – i.e. cash on delivery, bank transfers, etc." }, { "name": "Medias", "description": "Medias represent files that are hosted on our servers. Medias are uploaded directly to the underlying hosting service. To learn more about how medias work, please contact support." }, { "name": "Notes", "description": "Notes are snippets of text that can be attached to objects to provide extra context. Notes can be added to `Customer`, `Order`, and `Subscription` objects." }, { "name": "Order Protocols", "description": "A order protocol represents the order settings for an account." }, { "name": "Orders", "description": "An order is a customer's completed request to purchase one or more products. An order is created when a checkout is paid." }, { "name": "Parcel Templates", "description": "A parcel template is a saved set of package dimensions and weight that can be reused for shipping calculations." }, { "name": "Payment Failures", "description": "A payment failure represents an attempt to pay a checkout that failed." }, { "name": "Payment Intents", "description": "A payment intent represents the process of collecting a payment method from your customer." }, { "name": "Payment Methods", "description": "Payment method objects represent your customer's payment instruments." }, { "name": "Payout Groups", "description": "A payout group represents a group of payouts that are created together." }, { "name": "Payouts", "description": "A payout represents a payment to an affiliate." }, { "name": "Periods", "description": "A period represents a billing interval for a subscription." }, { "name": "Prices", "description": "Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices.\nThis approach lets you change prices without having to change your provisioning scheme. For example, you might have a single \\\"gold\\\" product that has prices for $10/month, $100/year, and €9 once." }, { "name": "Processors", "description": "A processor represents a connection to a third-party payment processor like Stripe." }, { "name": "Product Collections", "description": "A list of related products - used to categorize products." }, { "name": "Product Groups", "description": "A group of related products – used to configure which products a customer can switch between when updating a subscription." }, { "name": "Product Medias", "description": "Product medias represent a product's images." }, { "name": "Products", "description": "Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with Prices to configure pricing and Subscriptions." }, { "name": "Promotions", "description": "A Promotion represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon." }, { "name": "Purchases", "description": "A purchase represents a specific product that a customer has paid for (one-time products), or is currently paying for (recurring products via a subscription). The purchase model is a summary of all products that a customer current should have \"access\" to." }, { "name": "Referral Items", "description": "A referral item represents a specific line item within a referral." }, { "name": "Referrals", "description": "A referral represents a checkout that is associated with an affiliate." }, { "name": "Refunds", "description": "Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged." }, { "name": "Return Items", "description": "A return item represents a specific line item being returned from a customer within a return request." }, { "name": "Return Requests", "description": "A return request represents a return of products within an order from a customer." }, { "name": "Reviews", "description": "A review represents a customer's review of a product." }, { "name": "Review Medias", "description": "Review medias represent the media that is associated with a review." }, { "name": "Review Protocols", "description": "A review protocol represents the review settings for an account." }, { "name": "Shipments", "description": "A shipment represents a package being sent via a shipping provider (e.g. Shippo) with rate quoting, label purchasing, and tracking." }, { "name": "Shipping Methods", "description": "Shipping methods represent the different speeds/classes of shipping that a store offers – i.e. `Express`, `Ground`, etc." }, { "name": "Shipping Profiles", "description": "A shipping profile is a grouping of products that have the same shipping zones and rates. Each product can belong to one shipping profile." }, { "name": "Shipping Protocols", "description": "A shipping protocol represents the shipping settings for an account." }, { "name": "Shipping Rates", "description": "Shipping rates represent the specific rules for determining the cost of shipping based on the products within a checkout." }, { "name": "Shipping Zones", "description": "A shipping zone represents a geographical (group of countries) boundary for setting specific shipping rates within a shipping profile." }, { "name": "Statistics", "description": "A group of endpoints that provide high level statistics on resources." }, { "name": "Subscription Protocols", "description": "A subscription protocol represents the subscription settings for an account." }, { "name": "Subscriptions", "description": "A Subscription represents a recurring schedule to charge a customer on one of your processors." }, { "name": "Swaps", "description": "A swap represents a price that will be conditionally recommended to customers during checkout. Swaps are displayed in the checkout summary and can be easily toggled on or off. They are non-intrusive alternative to bumps, and offer customers an easy way to flip between two prices." }, { "name": "Tax Overrides", "description": "A tax override is a manual tax rate that will be applied to products in a collection or shipping within a specific tax zone." }, { "name": "Tax Protocols", "description": "A tax protocol represents the tax settings for an account." }, { "name": "Tax Registrations", "description": "A tax registration represents a tax zone that is enabled for an account. Taxes will not be calculated for checkouts within a tax zone unless a matching tax registration exists." }, { "name": "Tax Zones", "description": "A tax zone represents a geographic area (country and state combinations) that taxes can be calculated for." }, { "name": "Trackings", "description": "A tracking represents the tracking number information from a shipping courier." }, { "name": "Upsell Funnels", "description": "An upsell funnel represents a group of upsells that will be presented to customers after checkout in a specific order." }, { "name": "Upsells", "description": "An upsell represents a price (maybe discounted) that will be offered to customers after checkout." }, { "name": "Variant Options", "description": "Variant options represent the custom properties of a product – i.e. `Size`, `Color`, etc." }, { "name": "Variant Values", "description": "Variant values represent the custom values of a specific variant option. For example, a variant option named `Color` could have variant values of `Red` and `Blue`." }, { "name": "Variants", "description": "A variant represents one version of a product with several options. Each product can have a maximum of three variant options and a maximum of 100 variants." }, { "name": "Warehouses", "description": "A warehouse represents a \"ship from\" address that can be set as the account default for outbound shipments." }, { "name": "Verification Codes", "description": "Verification codes are short-lived authentication codes that can be used to verify access to an email address. They provide a secure way of granting access to the customer portal without requiring the customer to have a password.\nEach verification code is valid for 10 minutes, and you are limited to creating 1 every minute per email address." }, { "name": "Webhook Endpoints", "description": "You can configure webhook endpoints via the API to be notified about events that happen in your SureCart account.\nMost users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints." } ], "paths": { "/v1/cancellation_acts": { "get": { "summary": "List", "tags": [ "Cancellation Acts" ], "operationId": "list_cancellation_act", "description": "Returns a list of your cancellation acts.", "parameters": [ { "name": "ids[]", "in": "query", "description": "Only return objects with the given IDs.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "A limit on the number of items to be returned, between 1 and 100.", "required": false, "schema": { "type": "integer" } }, { "name": "live_mode", "in": "query", "description": "Only return objects that are live mode or test mode.", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of items you want returned.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "list", "pagination": { "count": 1, "limit": 20, "page": 1, "url": "/v1/cancellation_acts" }, "data": [ { "id": "ad2bf081-0a6f-49d7-8807-97a75f681c54", "object": "cancellation_act", "comment": null, "coupon_applied": false, "preserved": false, "performed_at": 1786008120, "cancellation_reason": "04d16dab-f720-444e-8bcb-e4353c6a33cb", "subscription": "a1529664-4518-4bfe-8c80-afe2326c0fba", "created_at": 1786008120, "updated_at": 1786008120 } ] }, "schema": { "$ref": "#/components/schemas/list_response" } } } } } } }, "/v1/cancellation_acts/{id}": { "get": { "summary": "Retrieve", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Cancellation Acts" ], "operationId": "retrieve_cancellation_act", "description": "Retrieves details of a specific cancellation reason.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "00e34714-ac4a-4c9d-9d0d-f57dbee7519d", "object": "cancellation_act", "comment": null, "coupon_applied": false, "preserved": false, "performed_at": 1786008120, "cancellation_reason": "b3212f23-6e3a-49b4-b5b1-8c034b5c94e4", "subscription": "982d47fc-a0a0-49c5-8db2-52ca1ba74a8e", "created_at": 1786008120, "updated_at": 1786008120 }, "schema": { "$ref": "#/components/schemas/cancellation_act_response" } } } } } } }, "/v1/cancellation_reasons": { "get": { "summary": "List", "tags": [ "Cancellation Reasons" ], "operationId": "list_cancellation_reason", "description": "Returns a list of your cancellation reasons.", "parameters": [ { "name": "ids[]", "in": "query", "description": "Only return objects with the given IDs.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "A limit on the number of items to be returned, between 1 and 100.", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "The page of items you want returned.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "list", "pagination": { "count": 1, "limit": 20, "page": 1, "url": "/v1/cancellation_reasons" }, "data": [ { "id": "3acebb04-7f7d-478e-a017-4407e6762fb2", "object": "cancellation_reason", "archived": false, "archived_at": null, "comment_enabled": false, "comment_prompt": null, "coupon_enabled": false, "label": "Too expensive", "position": 0, "discarded_at": null, "created_at": 1786008120, "updated_at": 1786008120 } ] }, "schema": { "$ref": "#/components/schemas/list_response" } } } } } }, "post": { "summary": "Create", "tags": [ "Cancellation Reasons" ], "operationId": "create_cancellation_reason", "description": "Creates a new cancellation reason.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "7aa69eef-e74c-43f6-b787-544e00d97560", "object": "cancellation_reason", "archived": false, "archived_at": null, "comment_enabled": false, "comment_prompt": null, "coupon_enabled": false, "label": "Switching to competitor", "position": 1, "discarded_at": null, "created_at": 1786008120, "updated_at": 1786008120 }, "schema": { "$ref": "#/components/schemas/cancellation_reason_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellation_reason": { "allOf": [ { "$ref": "#/components/schemas/cancellation_reason_body" } ] } }, "example": { "cancellation_reason": { "label": "Switching to competitor" } } } } } } } }, "/v1/cancellation_reasons/{id}": { "get": { "summary": "Retrieve", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Cancellation Reasons" ], "operationId": "retrieve_cancellation_reason", "description": "Retrieves details of a specific cancellation reason.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "13700e00-8019-4841-b0fd-ca131d3c3340", "object": "cancellation_reason", "archived": false, "archived_at": null, "comment_enabled": false, "comment_prompt": null, "coupon_enabled": false, "label": "Too expensive", "position": 0, "discarded_at": null, "created_at": 1786008121, "updated_at": 1786008121 }, "schema": { "$ref": "#/components/schemas/cancellation_reason_response" } } } } } }, "patch": { "summary": "Update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Cancellation Reasons" ], "operationId": "update_cancellation_reason", "description": "Updates a specific cancellation reason.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "420f7072-ce16-4605-88ff-ab465ccbb60c", "object": "cancellation_reason", "archived": false, "archived_at": null, "comment_enabled": false, "comment_prompt": null, "coupon_enabled": false, "label": "Too expensive", "position": 0, "discarded_at": null, "created_at": 1786008121, "updated_at": 1786008121 }, "schema": { "$ref": "#/components/schemas/cancellation_reason_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellation_reason": { "allOf": [ { "$ref": "#/components/schemas/cancellation_reason_body" } ] } }, "example": { "cancellation_reason": { "name": "Not using it" } } } } } } }, "delete": { "summary": "Delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Cancellation Reasons" ], "operationId": "delete_cancellation_reason", "description": "Deletes a specific cancellation reason.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "04bbae2a-b28d-479e-a2c3-9dd6fc1ddfb4", "object": "cancellation_reason", "deleted": true }, "schema": { "$ref": "#/components/schemas/model_destroy_response" } } } } } } }, "/v1/periods": { "get": { "summary": "List", "tags": [ "Periods" ], "operationId": "list_period", "description": "Returns a list of periods.", "parameters": [ { "name": "ids[]", "in": "query", "description": "Only return objects with the given IDs.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "A limit on the number of items to be returned, between 1 and 100.", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "The page of items you want returned.", "required": false, "schema": { "type": "integer" } }, { "name": "subscription_ids[]", "in": "query", "description": "Only return objects that belong to the given subscriptions.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "list", "pagination": { "count": 2, "limit": 20, "page": 1, "url": "/v1/periods" }, "data": [ { "id": "9e07d2db-69ea-426f-b8e8-2b6c04f3a30b", "object": "period", "ad_hoc_amount": null, "end_at": 1788686588, "next_payment_retry_at": null, "payment_retry_count": 0, "payoff": false, "quantity": 1, "renewal": false, "renewal_reminder_sent_at": null, "restoral": false, "skip_proration": false, "start_at": 1786008188, "status": "paid", "checkout": "e38409d8-6097-4cee-adf9-bd1bee986234", "price": "f1e51ddb-7ca2-45b5-9616-42686a4dc2bb", "subscription": "7565f1e4-d49c-43fe-8d90-2cd901c7f54f", "variant": null, "created_at": 1786008188, "updated_at": 1786008188 }, { "id": "d415d4f8-75f7-4b13-a68a-28458a5cffc1", "object": "period", "ad_hoc_amount": null, "end_at": 1788686588, "next_payment_retry_at": null, "payment_retry_count": 0, "payoff": false, "quantity": 1, "renewal": false, "renewal_reminder_sent_at": null, "restoral": false, "skip_proration": false, "start_at": 1786008188, "status": "paid", "checkout": "205e2736-8e05-44f6-bff8-34480f981d2c", "price": "f1e51ddb-7ca2-45b5-9616-42686a4dc2bb", "subscription": "7565f1e4-d49c-43fe-8d90-2cd901c7f54f", "variant": null, "created_at": 1786008188, "updated_at": 1786008188 } ] }, "schema": { "$ref": "#/components/schemas/list_response" } } } } } } }, "/v1/periods/{id}": { "patch": { "summary": "Update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Periods" ], "operationId": "update_period", "description": "Updates a specific period.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "cb98bbb4-b2e3-4e35-9969-9e864e3d9f25", "object": "period", "ad_hoc_amount": null, "end_at": 1786011788, "next_payment_retry_at": null, "payment_retry_count": 0, "payoff": false, "quantity": 1, "renewal": false, "renewal_reminder_sent_at": null, "restoral": false, "skip_proration": false, "start_at": 1786008188, "status": "paid", "checkout": "4a3c812e-a1ef-4aea-b932-801af9d0004b", "price": "0b194c70-ce09-4a0f-b8b4-acd291a3e2db", "subscription": "6b257a29-408c-4fde-a9b1-474d4d82e016", "variant": null, "created_at": 1786008188, "updated_at": 1786008188 }, "schema": { "$ref": "#/components/schemas/period_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "allOf": [ { "$ref": "#/components/schemas/period_body" } ] } }, "example": { "period": { "end_at": 1786011788 } } } } } } } }, "/v1/periods/{id}/retry_payment": { "patch": { "summary": "Retry Payment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Periods" ], "operationId": "retry_payment_period", "description": "Retries payment for a specific period.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "1cbfe67d-7ce2-4858-a823-3ffd40cdb065", "object": "period", "ad_hoc_amount": null, "end_at": 1788686589, "next_payment_retry_at": null, "payment_retry_count": 0, "payoff": false, "quantity": 1, "renewal": true, "renewal_reminder_sent_at": null, "restoral": false, "skip_proration": false, "start_at": 1786008189, "status": "payment_failed", "checkout": "2cf30102-944f-4f5c-9757-c59b46fc75f4", "price": "722a48be-a854-49f7-8884-2ceb24191538", "subscription": "6f97054b-c810-44ce-ac16-0304188c1ed7", "variant": null, "created_at": 1786008189, "updated_at": 1786008189 }, "schema": { "$ref": "#/components/schemas/period_response" } } } } } } }, "/v1/subscription_protocol": { "get": { "summary": "Retrieve", "tags": [ "Subscription Protocols" ], "operationId": "retrieve_subscription_protocol", "description": "Retrieves details of the current account's subscription protocol.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "9916998f-270c-4820-adc8-2f313c6a4078", "object": "subscription_protocol", "bypass_duplicate_trials": false, "cancel_behavior": "pending", "cancel_window_enabled": false, "cancel_window_days": 14, "default_payment_method_detach_enabled": false, "default_payment_method_fallback_enabled": true, "downgrade_behavior": "pending", "payment_retry_window_weeks": 1, "preservation_enabled": false, "preservation_locales": { "reasons_title": "We're sad to see you go", "reasons_description": "Before you cancel, please let us know the reason you're leaving.", "skip_link": "Never mind, I don't want to cancel.", "preserve_title": "Take {{ amount }} off your next payment?", "preserve_description": "We'd be happy to offer you {{ amount }} off your next payment if you'd stay with us.", "preserve_button": "Yes, I'll take it.", "cancel_link": "No thanks, I'd still like to cancel." }, "remind_at_period_percent_remaining": 10, "remind_after_days": null, "require_upfront_payment_method": true, "revoke_purchases_on_past_due": false, "upgrade_behavior": "immediate", "preservation_coupon": "99400e8a-1f88-4b39-8588-784d1ce2717b", "created_at": 1786008252, "updated_at": 1786008252 }, "schema": { "$ref": "#/components/schemas/subscription_protocol_response" } } } } } }, "patch": { "summary": "Update", "tags": [ "Subscription Protocols" ], "operationId": "update_subscription_protocol", "description": "Updates the current account's subscription protocol.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "adda0348-bb10-419c-a5e3-f4842eeec31b", "object": "subscription_protocol", "bypass_duplicate_trials": false, "cancel_behavior": "pending", "cancel_window_enabled": false, "cancel_window_days": 14, "default_payment_method_detach_enabled": false, "default_payment_method_fallback_enabled": true, "downgrade_behavior": "immediate", "payment_retry_window_weeks": 1, "preservation_enabled": false, "preservation_locales": { "reasons_title": "We're sad to see you go", "reasons_description": "Before you cancel, please let us know the reason you're leaving.", "skip_link": "Never mind, I don't want to cancel.", "preserve_title": "Take {{ amount }} off your next payment?", "preserve_description": "We'd be happy to offer you {{ amount }} off your next payment if you'd stay with us.", "preserve_button": "Yes, I'll take it.", "cancel_link": "No thanks, I'd still like to cancel." }, "remind_at_period_percent_remaining": 10, "remind_after_days": null, "require_upfront_payment_method": true, "revoke_purchases_on_past_due": false, "upgrade_behavior": "immediate", "preservation_coupon": "4a66fc28-f21b-4ccc-8c03-9d65b928d997", "created_at": 1786008253, "updated_at": 1786008253 }, "schema": { "$ref": "#/components/schemas/subscription_protocol_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_protocol": { "allOf": [ { "$ref": "#/components/schemas/subscription_protocol_body" } ] } }, "example": { "subscription_protocol": { "downgrade_behavior": "immediate" } } } } } } } }, "/v1/subscriptions/filter_schema": { "get": { "summary": "Filter Schema", "tags": [ "Subscriptions" ], "operationId": "filterSchemaSubscription", "description": "Retrieves the filter schema for subscriptions.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "rule_schema", "schema_id": "subscription", "attributes": [ { "key": "live_mode", "metadata": false, "supported_values": [], "type": "boolean", "operators": [ "is", "is_not" ] }, { "key": "cancel_at_period_end", "metadata": false, "supported_values": [], "type": "boolean", "operators": [ "is", "is_not" ] }, { "key": "created_at", "metadata": false, "supported_values": [], "type": "date", "operators": [ "is", "is_not", "is_after", "is_before", "is_on_or_after", "is_on_or_before" ] }, { "key": "status", "metadata": false, "supported_values": [ "active", "trialing", "past_due", "canceled", "completed", "incomplete" ], "type": "string", "operators": [ "is", "is_not", "contains", "not_contains", "start_with", "end_with" ] }, { "key": "customer.id", "metadata": false, "supported_values": [], "type": "uuid", "operators": [ "is", "is_not" ] }, { "key": "customer.email", "metadata": false, "supported_values": [], "type": "string", "operators": [ "is", "is_not", "contains", "not_contains", "start_with", "end_with" ] }, { "key": "product.id", "metadata": false, "supported_values": [], "type": "uuid", "operators": [ "is", "is_not" ] }, { "key": "product.name", "metadata": false, "supported_values": [], "type": "string", "operators": [ "is", "is_not", "contains", "not_contains", "start_with", "end_with" ] }, { "key": "price.id", "metadata": false, "supported_values": [], "type": "uuid", "operators": [ "is", "is_not" ] }, { "key": "price.name", "metadata": false, "supported_values": [], "type": "string", "operators": [ "is", "is_not", "contains", "not_contains", "start_with", "end_with" ] } ] }, "schema": { "$ref": "#/components/schemas/rule_schema_response" } } } } } } }, "/v1/subscriptions/filter": { "post": { "summary": "Filter", "tags": [ "Subscriptions" ], "operationId": "filterSubscription", "description": "Returns a list of subscriptions matching the supplied rule tree.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "list", "pagination": { "count": 1, "limit": 20, "page": 1, "url": "/v1/subscriptions/filter" }, "data": [ { "id": "74cd7686-50ed-4422-b47d-84d7a85ab3cb", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686653, "current_period_start_at": 1786008253, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/74cd7686-50ed-4422-b47d-84d7a85ab3cb", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "54f5ac75-1243-466a-b938-6085c8cc7524", "customer": "bc82372a-c4b9-498a-9224-b7b286fe99d4", "discount": null, "manual_payment_method": null, "payment_method": "c8048061-7983-4298-b05f-3858e3d0c444", "price": "6694013b-f459-449e-8768-76ffa138dbdb", "purchase": "c521f1b7-fc7e-40e2-a540-d51774931d81", "shipping_method": null, "variant": null, "created_at": 1786008253, "updated_at": 1786008253 } ] }, "schema": { "$ref": "#/components/schemas/list_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "allOf": [ { "$ref": "#/components/schemas/filter_body" } ] } }, "example": { "filter": { "type": "condition", "attribute_name": "status", "operator_label": "is", "comparison_value": "active" } } } } } } } }, "/v1/subscriptions": { "get": { "summary": "List", "tags": [ "Subscriptions" ], "operationId": "list_subscription", "description": "Returns a list of your subscriptions.", "parameters": [ { "name": "checkout_ids[]", "in": "query", "description": "Only return objects that belong to the given checkouts.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "customer_ids[]", "in": "query", "description": "Only return objects that belong to the given customers.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "finite", "in": "query", "description": "Only return subscriptions that are finite or not.", "required": false, "schema": { "type": "boolean" } }, { "name": "ids[]", "in": "query", "description": "Only return objects with the given IDs.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "A limit on the number of items to be returned, between 1 and 100.", "required": false, "schema": { "type": "integer" } }, { "name": "live_mode", "in": "query", "description": "Only return objects that are live mode or test mode.", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "The page of items you want returned.", "required": false, "schema": { "type": "integer" } }, { "name": "price_ids[]", "in": "query", "description": "Only return objects that belong to the given prices.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "product_ids[]", "in": "query", "description": "Only return objects that belong to the given products.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "purchase_ids[]", "in": "query", "description": "Only return objects that belong to the given purchases.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "query", "in": "query", "description": "The query to be used for full text search of this collection.", "required": false, "schema": { "type": "string" } }, { "name": "status[]", "in": "query", "description": "Only return objects with the given status.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "object": "list", "pagination": { "count": 1, "limit": 20, "page": 1, "url": "/v1/subscriptions" }, "data": [ { "id": "4fcfb763-75ad-41b4-b9ad-5882f841b2a0", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686653, "current_period_start_at": 1786008253, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/4fcfb763-75ad-41b4-b9ad-5882f841b2a0", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "93b8068d-41ba-4045-8225-fb164f09aa6b", "customer": "57d31c25-ce8b-4f55-b946-9d9b0cb57c5e", "discount": null, "manual_payment_method": null, "payment_method": "53ab15b5-751f-4eef-93a2-417a920990e7", "price": "5cd3658c-4ace-48a3-944a-a0481e720ff3", "purchase": "7136f974-8700-414d-b9e5-3699dfd92152", "shipping_method": null, "variant": null, "created_at": 1786008253, "updated_at": 1786008253 } ] }, "schema": { "$ref": "#/components/schemas/list_response" } } } } } }, "post": { "summary": "Create", "tags": [ "Subscriptions" ], "operationId": "create_subscription", "description": "Creates a new subscription.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "e0bb9a25-176a-41ff-b1a8-092388d2b1e1", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686654, "current_period_start_at": 1786008254, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/e0bb9a25-176a-41ff-b1a8-092388d2b1e1", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "incomplete", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "69412730-a5a3-4599-8871-054e0367b01e", "customer": "d9152126-99a9-4518-ac3f-b39cc3cf5430", "discount": null, "manual_payment_method": null, "payment_method": "cd43e232-3c58-4860-82af-00cdaf16600e", "price": "836742b7-9a34-4c59-a04b-330c87f69e1b", "purchase": "def572aa-5a48-4330-9291-95103721de9e", "shipping_method": null, "variant": null, "created_at": 1786008254, "updated_at": 1786008254 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription_body" } ] } }, "example": { "subscription": { "customer": "d9152126-99a9-4518-ac3f-b39cc3cf5430", "price": "836742b7-9a34-4c59-a04b-330c87f69e1b", "payment_method": "cd43e232-3c58-4860-82af-00cdaf16600e" } } } } } } } }, "/v1/subscriptions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Retrieve", "tags": [ "Subscriptions" ], "operationId": "retrieve_subscription", "description": "Retrieves details of a specific subscription.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "d1fdcf15-b271-4c75-9583-70308395e3b5", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686655, "current_period_start_at": 1786008255, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/d1fdcf15-b271-4c75-9583-70308395e3b5", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "ecaca4e0-c2e5-46a8-86fa-26178de52a1e", "customer": "959c6e6c-6d4a-4756-8e31-216192cedb28", "discount": null, "manual_payment_method": null, "payment_method": "e0c330dc-4cea-4ff9-bbfd-9f67feeb1dae", "price": "bc06a30c-b964-429f-abb4-c1c8381845f1", "purchase": "7bf24631-6334-4f87-b6e7-2360578c76e3", "shipping_method": null, "variant": null, "created_at": 1786008255, "updated_at": 1786008255 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } } }, "patch": { "summary": "Update", "tags": [ "Subscriptions" ], "operationId": "update_subscription", "description": "Updates a specific subscription.", "parameters": [ { "name": "refresh_price_version", "in": "query", "description": "When set to true the price that is associated with the subscription will be refreshed to reference the most recent version.", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_product_group_validation", "in": "query", "description": "When set to `true` you can update a subscription's price regardless of the product group it belongs to.", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_proration", "in": "query", "description": "When set to `true` the next period generated during an immediate update will not be prorated.", "required": false, "schema": { "type": "boolean" } }, { "name": "update_behavior", "in": "query", "description": "The strategy to use when updating this subscription – one of `immediate` or `pending`. If no value is provided, the corresponding subscription protocol `downgrade_behavior` or `upgrade_behavior` will be be used.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "ffba92c5-ea65-48fb-bb36-f6e1a00fdbee", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686656, "current_period_start_at": 1786008256, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/ffba92c5-ea65-48fb-bb36-f6e1a00fdbee", "quantity": 2, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 5800, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "1a6b6ec3-0811-4946-8d19-e869897dcbc9", "customer": "5f5fa47d-7165-4af8-8065-8aac920abe71", "discount": null, "manual_payment_method": null, "payment_method": "3ba6398a-088f-4038-818b-deac0925e827", "price": "79287f19-cbbe-4f42-8046-78b32bb488d1", "purchase": "a9499fdb-13bc-405b-945a-b6da60c782ef", "shipping_method": null, "variant": null, "created_at": 1786008255, "updated_at": 1786008256 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription_body" } ] } }, "example": { "subscription": { "quantity": 2 } } } } } } } }, "/v1/subscriptions/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Cancel/Pause", "tags": [ "Subscriptions" ], "operationId": "cancel/pause_subscription", "description": "Cancels a specific subscription. If a `restore_at` value is provided, the subscription will be effectively \"paused\" until that date when it will automatically renew.", "parameters": [ { "name": "cancel_behavior", "in": "query", "description": "The strategy to use when canceling this subscription – one of `immediate` or `pending`. If no value is provided, the subscription protocol `cancel_behavior` will be be used.", "required": false, "schema": { "type": "string" } }, { "name": "cancellation_act[cancellation_reason_id]", "in": "query", "description": "The cancellation reason that should be set on the cancellation act when the subscription is canceled or preserved.", "required": false, "schema": { "type": "string" } }, { "name": "cancellation_act[comment]", "in": "query", "description": "The comment that should be set on the cancellation act when the subscription is canceled or preserved.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "1283a3c9-79c8-41ea-98e1-a18d706c0808", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": true, "currency": "usd", "current_period_end_at": 1788686657, "current_period_start_at": 1786008257, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/1283a3c9-79c8-41ea-98e1-a18d706c0808", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": 1791278657, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": "3b2371f8-02ae-460a-a821-5f91d3314013", "current_period": "f31b2fea-c247-4c4c-869f-db85c3f71feb", "customer": "ba676335-c73d-4d66-94d1-2466eb3b0925", "discount": null, "manual_payment_method": null, "payment_method": "d4784072-130d-49ff-a28f-e95ec6f69ea5", "price": "0adea36c-adc4-43ac-909b-306d3676c2c2", "purchase": "75a36e5b-6c56-4ab7-8b61-b0b3928a900d", "shipping_method": null, "variant": null, "created_at": 1786008257, "updated_at": 1786008257 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription_cancel_body" } ] } }, "example": { "subscription": { "restore_at": "2026-10-06 09:24:17 UTC" } } } } } } } }, "/v1/subscriptions/{id}/complete": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Complete", "tags": [ "Subscriptions" ], "operationId": "complete_subscription", "description": "Completes a specific subscription.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "2aea0479-bcc3-4fc4-9ecb-bc43a9d62a27", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686657, "current_period_start_at": 1786008257, "ended_at": 1786008257, "finite": true, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": true, "portal_url": "http://app.example.com/portal_redirect/subscriptions/2aea0479-bcc3-4fc4-9ecb-bc43a9d62a27", "quantity": 1, "remaining_period_count": 5, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "completed", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "4094870a-7580-432b-9248-8bcc9f032964", "customer": "cb56df5d-4a36-4bea-8733-0e1ddb4614d4", "discount": null, "manual_payment_method": null, "payment_method": "f6b43f0a-6b94-4453-92d3-aa12624539db", "price": "c7541675-5f4b-4d22-b91d-3da126493bb8", "purchase": "fa917728-54a0-4539-92af-a4b47a54f125", "shipping_method": null, "variant": null, "created_at": 1786008257, "updated_at": 1786008257 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } } } }, "/v1/subscriptions/{id}/pay_off": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Pay Off", "tags": [ "Subscriptions" ], "operationId": "pay_off_subscription", "description": "Pays off all remaining periods for a specific subscription.", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "22d58b15-2d1b-40c5-ba32-7b7e0e5dc6e7", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1786008258, "current_period_start_at": 1786008258, "ended_at": null, "finite": true, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": true, "portal_url": "http://app.example.com/portal_redirect/subscriptions/22d58b15-2d1b-40c5-ba32-7b7e0e5dc6e7", "quantity": 1, "remaining_period_count": 5, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "23b30a0c-55d0-4a86-aa18-902a7c0b3657", "customer": "f7b01d63-2769-495e-a1d0-205522ec5313", "discount": null, "manual_payment_method": null, "payment_method": "324bec41-8354-49b1-aa4c-af2661ea7211", "price": "43be04ec-a1e3-4de9-8737-4b7916c8df39", "purchase": "a2c61519-53fd-44fd-b772-c57169ee72cd", "shipping_method": null, "variant": null, "created_at": 1786008258, "updated_at": 1786008258 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } } } }, "/v1/subscriptions/{id}/preserve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Preserve", "tags": [ "Subscriptions" ], "operationId": "preserve_subscription", "description": "Preserves a specific subscription.", "parameters": [ { "name": "cancellation_act[cancellation_reason_id]", "in": "query", "description": "The cancellation reason that should be set on the cancellation act when the subscription is canceled or preserved.", "required": false, "schema": { "type": "string" } }, { "name": "cancellation_act[comment]", "in": "query", "description": "The comment that should be set on the cancellation act when the subscription is canceled or preserved.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "a7eedb3e-a0ea-41f5-b5f1-41a244c5bdd2", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686659, "current_period_start_at": 1786008259, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/a7eedb3e-a0ea-41f5-b5f1-41a244c5bdd2", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": null, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": "7f9616dd-8587-4f9e-ba9f-7a642460891c", "current_period": "d7e401e6-7990-4a09-bf07-4f8f193624b6", "customer": "642de099-b98d-4ba8-a5c8-7fe48d2282a4", "discount": null, "manual_payment_method": null, "payment_method": "c1effa0b-d450-40c0-81d5-5b411e98f5cc", "price": "08e0cf9a-d726-4b7f-8435-a0566adba2ac", "purchase": "c5723616-54fb-4a12-a6d9-27bf644cba51", "shipping_method": null, "variant": null, "created_at": 1786008259, "updated_at": 1786008259 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } } } }, "/v1/subscriptions/{id}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Restore", "tags": [ "Subscriptions" ], "operationId": "restore_subscription", "description": "Restores a specific subscription.", "parameters": [ { "name": "refresh_price_version", "in": "query", "description": "When set to true the price that is associated with the subscription will be refreshed to reference the most recent version.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "8a8183c1-31ff-4854-99ef-01abe6aab80b", "object": "subscription", "ad_hoc_amount": null, "affiliation_expires_at": null, "cancel_at_period_end": false, "currency": "usd", "current_period_end_at": 1788686660, "current_period_start_at": 1786008260, "ended_at": null, "finite": false, "last_renewal_reminder_sent_at": null, "live_mode": true, "manual_payment": false, "metadata": {}, "pending_update": {}, "price_readonly": false, "portal_url": "http://app.example.com/portal_redirect/subscriptions/8a8183c1-31ff-4854-99ef-01abe6aab80b", "quantity": 1, "remaining_period_count": null, "restart_on_completed": false, "restore_at": 1786008260, "subtotal_amount": 2900, "status": "active", "tax_enabled": false, "trial_end_at": null, "trial_start_at": null, "variant_options": null, "affiliation": null, "current_cancellation_act": null, "current_period": "df579979-ebc9-4226-9daa-5e462460c1f0", "customer": "1f353d55-542d-489b-9128-1d7b32162ee9", "discount": null, "manual_payment_method": null, "payment_method": "8184d21d-5cec-4a8d-abd4-847e0602369e", "price": "84b9b66f-e556-458f-85e1-cf6bc796b69a", "purchase": "730dc120-adae-4e7a-ba21-10f1b3e9dcb6", "shipping_method": null, "variant": null, "created_at": 1786008259, "updated_at": 1786008260 }, "schema": { "$ref": "#/components/schemas/subscription_response" } } } } } } }, "/v1/subscriptions/{id}/upcoming_period": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Upcoming Period", "tags": [ "Subscriptions" ], "operationId": "upcoming_period_subscription", "description": "Generates a preview of the upcoming period.", "parameters": [ { "name": "pay_off", "in": "query", "description": "When set to `true` the upcoming period will simulate paying off the subscription.", "required": false, "schema": { "type": "boolean" } }, { "name": "refresh_price_version", "in": "query", "description": "When set to true the price that is associated with the subscription will be refreshed to reference the most recent version.", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_product_group_validation", "in": "query", "description": "When set to `true` you can update a subscription's price regardless of the product group it belongs to.", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_proration", "in": "query", "description": "When set to `true` the next period generated during an immediate update will not be prorated.", "required": false, "schema": { "type": "boolean" } }, { "name": "update_behavior", "in": "query", "description": "The strategy to use when updating this subscription – one of `immediate` or `pending`. If no value is provided, the corresponding subscription protocol `downgrade_behavior` or `upgrade_behavior` will be be used.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "7aef4c59-4290-443b-b3f9-fc274d183f67", "object": "period", "ad_hoc_amount": null, "end_at": 1788686661, "next_payment_retry_at": null, "payment_retry_count": 0, "payoff": false, "quantity": 2, "renewal": false, "renewal_reminder_sent_at": null, "restoral": false, "skip_proration": false, "start_at": 1786008261, "status": "draft", "checkout": "931f3b76-9c43-4b97-9da0-fdedbecafd25", "price": "593a9283-56a1-499a-aa3b-aca2d3706c1b", "subscription": "2809b224-8811-4ed4-915e-286f61545f66", "variant": null, "created_at": 1786008261, "updated_at": 1786008261 }, "schema": { "$ref": "#/components/schemas/period_response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription_body" } ] } }, "example": { "subscription": { "quantity": 2 } } } } } } } } }, "info": { "title": "SureCart Subscriptions API", "description": "Subscription management including periods, cancellations, and subscription protocols", "termsOfService": "https://surecart.com/terms-and-conditions", "version": "1.0" } }