{ "openapi": "3.1.1", "info": { "title": "Bias API", "version": "1.0.0" }, "servers": [ { "url": "https://api.biaspay.com" } ], "components": { "securitySchemes": { "auth": { "type": "http", "scheme": "bearer", "description": "An API key created from the Bias dashboard" } }, "schemas": { "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "$ref": "#/components/schemas/ServerError" }, { "$ref": "#/components/schemas/PaymentError" }, { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/RateLimitError" } ] }, "List": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": {}, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "has_more": false } }, "InvalidRequestError": { "type": "object", "properties": { "object": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error" }, "live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string", "enum": [ "already_expired", "decryption_failed", "amount_exceeds_available", "amount_mismatch", "customer_mismatch", "invoice_mismatch", "incorrect_http_method", "invalid_api_key", "invalid_authorization_scheme", "invalid_parameters", "invoice_not_sendable", "invoice_not_payable", "malformed_request", "resource_deactivated", "resource_immutable", "resource_in_use", "resource_missing", "resource_unassignable", "session_closed", "suspicious_request", "uncancelable_payment", "uncapturable_payment", "unrefundable_payment", "payment_method_unavailable", "url_invalid", "wrong_file_purpose" ] }, { "type": "null" } ], "x-enum-descriptions": { "already_expired": "The resource has already expired.", "amount_exceeds_available": "The requested amount exceeds the available amount on the object.", "amount_mismatch": "The payment amount does not match the required amount.", "customer_mismatch": "The customer ID on the existing object does not match the customer ID in the request.", "decryption_failed": "One or more payment method fields could not be decrypted. Ensure the correct session public key was used.", "invoice_mismatch": "The invoice ID on the existing object does not match the invoice ID in the request.", "incorrect_http_method": "The HTTP method used in the request is not supported by the resource.", "invalid_api_key": "The API key used in the request is invalid.", "invalid_authorization_scheme": "The authorization scheme used in the request is invalid.", "invalid_parameters": "The parameters used in the request are invalid.", "invoice_not_sendable": "The invoice cannot be sent in its current state.", "invoice_not_payable": "The invoice cannot be paid in its current state.", "malformed_request": "The request does not conform to its stated content type.", "resource_deactivated": "The resource has been deactivated.", "resource_immutable": "The resource is immutable.", "resource_in_use": "The resource is in use and cannot be deleted.", "resource_missing": "The resource does not exist.", "resource_unassignable": "The resource is unassignable to the target object.", "session_closed": "The checkout session is not open and new payments cannot be created for it.", "suspicious_request": "The request content or parameters contain patterns that appear suspicious or potentially malicious.", "uncancelable_payment": "The payment is uncancelable.", "uncapturable_payment": "The payment is uncapturable.", "unrefundable_payment": "The payment is unrefundable.", "payment_method_unavailable": "The requested payment method type is not enabled on your account.", "url_invalid": "The request URL is invalid.", "wrong_file_purpose": "One or more files do not have the required purpose for this operation." } }, "message": { "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "live", "code", "message", "param" ], "additionalProperties": false } }, "required": [ "object", "error" ], "additionalProperties": false }, "RateLimitError": { "type": "object", "properties": { "object": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "const": "rate_limit_error" }, "live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "code": { "type": "null", "const": null }, "message": { "type": "string" }, "param": { "type": "null", "const": null } }, "required": [ "type", "live", "code", "message", "param" ], "additionalProperties": false } }, "required": [ "object", "error" ], "additionalProperties": false }, "ServerError": { "type": "object", "properties": { "object": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "const": "server_error" }, "live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "code": { "type": "null", "const": null }, "message": { "type": "string" }, "param": { "type": "null", "const": null } }, "required": [ "type", "live", "code", "message", "param" ], "additionalProperties": false } }, "required": [ "object", "error" ], "additionalProperties": false }, "CheckoutSessionExpand": { "type": "object", "properties": { "payments": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PaymentExpand" } ] }, "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] }, "invoice": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/InvoiceExpand" } ] }, "line_items": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/LineItemExpand" } ] } }, "additionalProperties": false }, "PaymentExpand": { "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] }, "dispute": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/DisputeExpand" } ] }, "invoice": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/InvoiceExpand" } ] }, "payment_method": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] } }, "additionalProperties": false } ] }, "session": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CheckoutSessionExpand" } ] } }, "additionalProperties": false }, "CustomerExpand": { "type": "object", "properties": {}, "additionalProperties": false }, "DisputeExpand": { "type": "object", "properties": { "evidence": { "description": "Expands all evidence fields.", "type": "boolean" }, "payment": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PaymentExpand" } ] } }, "additionalProperties": false }, "InvoiceExpand": { "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] }, "payments": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PaymentExpand" } ] }, "line_items": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/LineItemExpand" } ] }, "attachments": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/FileExpand" } ] }, "credit_notes": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CreditNoteExpand" } ] } }, "additionalProperties": false }, "LineItemExpand": { "type": "object", "properties": { "product": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ProductExpand" } ] }, "price": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PriceExpand" } ] }, "discounts": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/DiscountExpand" } ] } }, "additionalProperties": false }, "ProductExpand": { "type": "object", "properties": { "images": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/FileExpand" } ] }, "default_price": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PriceExpand" } ] }, "prices": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PriceExpand" } ] } }, "additionalProperties": false }, "FileExpand": { "type": "object", "properties": {}, "additionalProperties": false }, "PriceExpand": { "type": "object", "properties": { "product": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ProductExpand" } ] } }, "additionalProperties": false }, "DiscountExpand": { "type": "object", "properties": { "applies_to": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ProductExpand" } ] } }, "additionalProperties": false }, "CreditNoteExpand": { "type": "object", "properties": { "invoice": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/InvoiceExpand" } ] }, "line_items": { "type": "boolean" } }, "additionalProperties": false }, "CheckoutSession": { "type": "object", "properties": { "object": { "type": "string", "const": "checkout_session", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "amount": { "type": "integer", "description": "The total of the checkout session in cents." }, "amount_collected": { "type": "integer", "description": "The amount collected from the customer in successful payments." }, "dual_pricing": { "anyOf": [ { "type": "object", "properties": { "rate": { "type": "number", "description": "The dual pricing rate as a percentage. For example, `3` represents 3%. This rate is applied only when the payment method type is `card`." } }, "required": [ "rate" ], "additionalProperties": false }, { "type": "null" } ], "description": "Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is." }, "client_details": { "anyOf": [ { "type": "object", "properties": { "fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A unique fingerprint identifying the client device or browser." }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The IP address of the client that initiated the checkout session." }, "device_type": { "anyOf": [ { "$ref": "#/components/schemas/SessionDeviceType" }, { "type": "null" } ], "description": "The type of device the client used to initiate the checkout session." } }, "required": [ "fingerprint", "ip_address", "device_type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Information about the client that initiated the checkout session. Populated automatically from the client environment." }, "client_secret": { "type": "string", "description": "The client secret for the checkout session. Return this value to checkout elements to initialize the payment form." }, "customer": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Customer" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The customer associated with the checkout session." }, "customer_details": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s email address." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s full name or business name." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s phone number." } }, "required": [ "email", "name", "phone" ], "additionalProperties": false, "description": "The customer’s details entered in this session. When the session completes, the created customer will inherit these values." }, "payments": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, { "type": "null" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The payments associated with the checkout session." }, "invoice": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Invoice" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The invoice this checkout session was created from." }, "line_items": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, { "type": "null" } ], "description": "The line items representing the products or services being purchased." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "mode": { "$ref": "#/components/schemas/SessionMode" }, "payment_method_types": { "type": "array", "items": { "type": "string", "enum": [ "card", "us_bank_account" ], "description": "The type of the payment method.", "x-enum-descriptions": { "card": "Credit or debit card.", "us_bank_account": "US bank account (ACH)." } }, "description": "The payment method types accepted by this checkout session." }, "status": { "$ref": "#/components/schemas/SessionStatus" }, "submit_label": { "$ref": "#/components/schemas/SessionSubmitLabel" } }, "required": [ "object", "id", "live", "created_at", "amount", "amount_collected", "dual_pricing", "client_details", "client_secret", "customer", "customer_details", "payments", "invoice", "line_items", "metadata", "mode", "payment_method_types", "status", "submit_label" ], "additionalProperties": false, "example": { "object": "checkout_session", "id": "cs_MyJuJvswjRM54vPXr6qBh2", "live": false, "created_at": 1750000000000, "amount": 1000, "amount_collected": 1000, "dual_pricing": null, "client_details": null, "client_secret": "uEyLI6rmFylTwIBik5cpn8ge", "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "customer_details": { "email": null, "name": null, "phone": null }, "payments": [], "invoice": null, "line_items": [], "metadata": {}, "mode": "payment", "payment_method_types": [ "card", "us_bank_account" ], "status": "complete", "submit_label": "auto" } }, "SessionDeviceType": { "type": "string", "enum": [ "mobile", "desktop" ], "description": "The type of device the client used to initiate the checkout session.", "x-enum-descriptions": { "mobile": "The client is on a mobile device.", "desktop": "The client is on a desktop device." } }, "Customer": { "type": "object", "properties": { "object": { "type": "string", "const": "customer", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the customer has been deleted." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s full name or business name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s email address." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer‘s phone number." }, "external_sync": { "anyOf": [ { "$ref": "#/components/schemas/ExternalSync" }, { "type": "null" } ], "description": "The external system record linked to this customer, if any." }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "updated_at", "deleted", "name", "email", "phone", "external_sync", "metadata" ], "additionalProperties": false, "example": { "object": "customer", "id": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "John Doe", "email": "john@bias.dev", "phone": null, "external_sync": null, "metadata": {} } }, "ExternalSync": { "type": "object", "properties": { "provider": { "type": "string", "const": "quickbooks" }, "external_id": { "type": "string" } }, "required": [ "provider", "external_id" ], "additionalProperties": false, "description": "A lightweight link to an externally synced record." }, "Metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] }, "description": "A [key-value store](/api-reference/metadata) that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use." }, "Payment": { "type": "object", "properties": { "object": { "type": "string", "const": "payment", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "amount": { "type": "integer", "description": "The amount of the payment in cents." }, "amount_capturable": { "type": "integer", "description": "The amount of the payment that is available to be captured." }, "amount_received": { "type": "integer", "description": "The amount of the payment that has been received (captured)." }, "amount_refunded": { "type": "integer", "description": "The amount of the payment that has been refunded." }, "capture_method": { "type": "string", "enum": [ "automatic", "manual" ], "description": "When to capture the payment.", "x-enum-descriptions": { "automatic": "Capture the payment immediately.", "manual": "Leave the payment requires_capture. You may [capture](/payments#capture) the payment later to collect funds." } }, "customer": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Customer" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The customer associated with the payment." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A description of the payment’s purpose." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "payment_error": { "anyOf": [ { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The error message. This message can be shown to the customer." }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The parameter that caused the error." }, "code": { "anyOf": [ { "$ref": "#/components/schemas/PaymentDeclineCode" }, { "type": "null" } ], "description": "The decline code from the issuer." }, "network_decline_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The decline code from the payment network." } }, "required": [ "message", "param", "code", "network_decline_code" ], "additionalProperties": false }, { "type": "null" } ], "description": "For `failed` payments. Contains information about the failure that occurred." }, "payment_method": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/PaymentMethod" } ], "x-expandable": true, "description": "Expandable. The payment method used for the payment." }, "statement_descriptor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The statement descriptor for the payment." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "dispute": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Dispute" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The latest dispute received for this payment." }, "session": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CheckoutSession" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The checkout session this payment was created from." }, "invoice": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Invoice" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The invoice this payment was created from." } }, "required": [ "object", "live", "id", "created_at", "amount", "amount_capturable", "amount_received", "amount_refunded", "capture_method", "customer", "description", "metadata", "payment_error", "payment_method", "statement_descriptor", "status", "dispute", "session", "invoice" ], "additionalProperties": false, "example": { "object": "payment", "live": false, "id": "pay_lUY2g0TuPzN9qi4couahd3", "created_at": 1750000000000, "amount": 1000, "amount_capturable": 1000, "amount_received": 0, "amount_refunded": 0, "capture_method": "automatic", "customer": "customer", "description": "Payment for order 123", "dispute": null, "invoice": null, "metadata": {}, "payment_error": null, "payment_method": "payment_method", "session": "checkout_session", "statement_descriptor": null, "status": "succeeded" } }, "PaymentDeclineCode": { "type": "string", "enum": [ "authentication_required", "debit_not_authorized", "call_issuer", "card_not_supported", "card_velocity_exceeded", "account_closed", "currency_not_supported", "do_not_honor", "duplicate_transaction", "expired_card", "fraudulent", "generic_decline", "incorrect_cvc", "incorrect_number", "incorrect_postal_code", "incorrect_address", "insufficient_funds", "invalid_account", "issuer_not_available", "lost_card", "new_account_information_available", "no_action_taken", "no_account", "not_permitted", "offline_pin_required", "online_or_offline_pin_required", "pickup_card", "pin_try_exceeded", "processing_error", "reenter_transaction", "restricted_card", "security_violation", "service_not_allowed", "stolen_card", "stop_payment_order", "transaction_not_allowed", "try_again_later", "withdrawal_count_limit_exceeded" ] }, "PaymentMethod": { "type": "object", "properties": { "object": { "type": "string", "const": "payment_method", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "active": { "type": "boolean", "description": "Whether the payment method can be used for new payments. Has a value of `false` if the payment method has been deactivated or if it was created without `setup_future_usage`." }, "billing_details": { "type": "object", "properties": { "address": { "type": "object", "properties": { "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address city." }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ], "description": "The address country." }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address (e.g. unit or floor number)." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address postal code." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address state." } }, "required": [ "city", "country", "line1", "line2", "postal_code", "state" ], "additionalProperties": false, "description": "The cardholder’s billing address." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cardholder’s name." } }, "required": [ "address", "name" ], "additionalProperties": false, "description": "Billing information for the payment method." }, "card": { "anyOf": [ { "$ref": "#/components/schemas/Card" }, { "type": "null" } ], "description": "The payment method’s card details." }, "us_bank_account": { "anyOf": [ { "$ref": "#/components/schemas/UsBankAccount" }, { "type": "null" } ], "description": "The payment method’s US bank account details." }, "type": { "type": "string", "enum": [ "card", "us_bank_account" ], "description": "The type of the payment method.", "x-enum-descriptions": { "card": "Credit or debit card.", "us_bank_account": "US bank account (ACH)." } }, "customer": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Customer" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The customer this payment method is attached to." } }, "required": [ "object", "id", "live", "created_at", "active", "billing_details", "card", "us_bank_account", "type", "customer" ], "additionalProperties": false, "example": { "object": "payment_method", "id": "pm_VQ9SaYquIZTG2l0uRsmUr4", "live": false, "created_at": 1750000000000, "active": true, "billing_details": { "address": { "city": "Los Angeles", "country": "US", "line1": "123 Main Street", "line2": null, "postal_code": "90001", "state": "CA" }, "name": "John Doe" }, "card": { "object": "card", "live": false, "id": "card_inJ1dWsOEGezQOWd69qUW5", "created_at": 1750000000000, "bin": "42424242", "brand": "visa", "checks": { "address_line_1": "pass", "address_postal_code": "pass", "cvc": "pass" }, "country": "US", "exp_month": 1, "exp_year": 2030, "funding": "credit", "issuer": "Wells Fargo", "last4": "4242" }, "us_bank_account": null, "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "type": "card" } }, "CountryCode": { "type": "string", "enum": [ "AC", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TA", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-character uppercase ISO 3166-1 alpha-2 country code" }, "Card": { "type": "object", "properties": { "object": { "type": "string", "const": "card", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "bin": { "type": "string", "minLength": 6, "maxLength": 8, "description": "The first 6 to 8 digits of the card number" }, "brand": { "type": "string", "description": "The card brand, e.g. Visa, Mastercard, etc." }, "checks": { "type": "object", "properties": { "address_line_1": { "anyOf": [ { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ] }, { "type": "null" } ], "description": "The AVS status for the street address number" }, "address_postal_code": { "anyOf": [ { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ] }, { "type": "null" } ], "description": "The AVS status for the postal code" }, "cvc": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ] }, { "type": "null" } ] }, { "type": "null" } ], "description": "The CVC verification status" } }, "required": [ "address_line_1", "address_postal_code", "cvc" ], "additionalProperties": false, "description": "Card verification check statuses" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The card country" }, "exp_month": { "type": "integer", "description": "The card expiration month" }, "exp_year": { "type": "integer", "description": "The card expiration year" }, "funding": { "type": "string", "enum": [ "credit", "debit", "prepaid", "unknown" ], "description": "The card funding source" }, "issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The card issuer, e.g. Chase Bank, Wells Fargo, etc." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "The last 4 digits of the card number" } }, "required": [ "object", "id", "live", "created_at", "bin", "brand", "checks", "country", "exp_month", "exp_year", "funding", "issuer", "last4" ], "additionalProperties": false }, "UsBankAccount": { "type": "object", "properties": { "object": { "type": "string", "const": "us_bank_account", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "account_type": { "type": "string", "enum": [ "checking", "savings" ], "description": "The type of bank account." }, "bank_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the bank." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "The last 4 digits of the account number." }, "routing_number": { "type": "string", "minLength": 9, "maxLength": 9, "description": "The 9-digit ACH routing number." } }, "required": [ "object", "id", "created_at", "account_type", "bank_name", "last4", "routing_number" ], "additionalProperties": false, "example": { "id": "usba_123", "object": "us_bank_account", "account_type": "checking", "bank_name": "Test Bank", "created_at": 12321093923, "last4": "6789", "routing_number": "110000000" } }, "PaymentStatus": { "type": "string", "enum": [ "requires_capture", "processing", "canceled", "succeeded", "failed" ], "description": "The status of the payment.", "x-enum-descriptions": { "succeeded": "The payment was successfully captured.", "processing": "The payment is pending and will be captured shortly.", "requires_capture": "The payment has been authorized but requires a capture to succeed.", "canceled": "The payment was canceled (voided after authorization).", "failed": "The payment failed. See `payment_error` for details." } }, "Dispute": { "type": "object", "properties": { "object": { "type": "string", "const": "dispute", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "status": { "$ref": "#/components/schemas/DisputeStatus" }, "amount": { "type": "integer", "description": "The disputed amount." }, "reason": { "$ref": "#/components/schemas/DisputeReason" }, "payment": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Payment" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The payment that is disputed. `null` only if the dispute was expanded from a payment object." }, "evidence": { "type": "object", "properties": { "access_activity_log": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Server or user activity logs demonstrating customer access or download of the purchased digital service or product. Include IP addresses, timestamps, and detailed recorded activity." }, "billing_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The billing address provided by the customer." }, "cancellation_policy": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Your subscription cancellation policy, as presented to the customer." }, "cancellation_policy_disclosure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of how and when the customer was shown your refund or cancellation policy before purchase." }, "cancellation_rebuttal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Justification for why the customer's subscription was not canceled." }, "customer_communication": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Relevant communication with the customer, such as emails proving product receipt, usage, or satisfaction." }, "customer_email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "description": "The customer's email address." }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's name." }, "customer_purchase_ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The IP address used by the customer during the purchase." }, "customer_signature": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Document or contract displaying the customer's signature." }, "duplicate_charge_documentation": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Documentation uniquely identifying the prior charge, such as a receipt or shipping label. Pair with a similar document from the disputed payment to prove that transactions are separate." }, "duplicate_charge_explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the differences between the disputed charge and the apparent duplicate prior charge." }, "duplicate_payment": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Payment" } ], "x-expandable": true }, { "type": "null" } ], "description": "The payment ID for the prior charge that appears to be a duplicate of the disputed charge." }, "product_category": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "physical", "digital", "offline_service", "event", "booking" ] }, { "type": "string" } ] }, { "type": "null" } ], "description": "Category of product or service purchased." }, "product_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the product or service sold." }, "receipt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Receipt or message sent to the customer notifying them of the charge." }, "refund_policy": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Your refund policy, as shown to the customer." }, "refund_policy_disclosure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Documentation showing the customer was presented with your refund policy before purchase." }, "refund_refusal_explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Justification for why the customer is not entitled to a refund." }, "service_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date the customer received or began receiving the purchased service, in a clear human-readable format." }, "service_documentation": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Proof of service provided to the customer, such as a signed contract or work order." }, "shipping_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address to which a physical product was shipped. Include complete address information when possible." }, "shipping_carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The delivery service(s) used to ship the physical product. Separate multiple carriers with commas." }, "shipping_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date the physical product began its route to the shipping address, in a clear human-readable format." }, "shipping_documentation": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Proof of product shipment to the customer's provided address, such as a shipment receipt or shipping label. Should show the full shipping address if possible." }, "shipping_tracking_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking number(s) for the physical product from the delivery service. Separate multiple numbers with commas." }, "terms_and_conditions": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Your terms and conditions, as presented to the customer." }, "uncategorized_file": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/File" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. Any additional evidence or statements." }, "uncategorized_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Any additional evidence or statements in text form." }, "win_reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "withdrawn", "refunded", "not_fraudulent" ] }, { "type": "string" } ] }, { "type": "null" } ], "description": "The reason you should win this dispute." } }, "required": [ "access_activity_log", "billing_address", "cancellation_policy", "cancellation_policy_disclosure", "cancellation_rebuttal", "customer_communication", "customer_email", "customer_name", "customer_purchase_ip", "customer_signature", "duplicate_charge_documentation", "duplicate_charge_explanation", "duplicate_payment", "product_category", "product_description", "receipt", "refund_policy", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "service_documentation", "shipping_address", "shipping_carrier", "shipping_date", "shipping_documentation", "shipping_tracking_number", "terms_and_conditions", "uncategorized_file", "uncategorized_text", "win_reason" ], "additionalProperties": false }, "evidence_details": { "type": "object", "properties": { "due_by": { "type": "number", "description": "The deadline by which you must respond to the dispute." }, "submitted_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The date the dispute was submitted." } }, "required": [ "due_by", "submitted_at" ], "additionalProperties": false }, "payment_method_details": { "type": "object", "properties": { "card": { "type": "object", "properties": { "case_type": { "type": "string", "enum": [ "chargeback", "inquiry" ], "description": "Whether the dispute is an inquiry (retrieval) or a chargeback." }, "network_reason_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The reason code from the card network." } }, "required": [ "case_type", "network_reason_code" ], "additionalProperties": false } }, "required": [ "card" ], "additionalProperties": false }, "metadata": { "description": "Metadata about the dispute.", "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "status", "amount", "reason", "payment", "evidence", "evidence_details", "payment_method_details", "metadata" ], "additionalProperties": false, "examples": [ { "object": "dispute", "id": "dis_iQ8bYlW1rHvDbKagXGTFj", "live": false, "created_at": 1750000000000, "amount": 1000, "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy_disclosure": null, "cancellation_policy": null, "cancellation_rebuttal": null, "customer_communication": null, "customer_email": null, "customer_name": null, "customer_purchase_ip": null, "customer_signature": null, "duplicate_charge_documentation": null, "duplicate_charge_explanation": null, "duplicate_payment": null, "product_category": null, "product_description": null, "receipt": null, "refund_policy_disclosure": null, "refund_policy": null, "refund_refusal_explanation": null, "service_date": null, "service_documentation": null, "shipping_address": null, "shipping_carrier": null, "shipping_date": null, "shipping_documentation": null, "shipping_tracking_number": null, "terms_and_conditions": null, "uncategorized_file": null, "uncategorized_text": null, "win_reason": null }, "evidence_details": { "due_by": 1752000000000, "submitted_at": null }, "metadata": {}, "payment_method_details": { "card": { "case_type": "chargeback", "network_reason_code": null } }, "payment": null, "reason": "duplicate", "status": "needs_response" } ] }, "DisputeStatus": { "type": "string", "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The status of the dispute.", "x-enum-descriptions": { "needs_response": "The dispute requires a response from you before the deadline.", "under_review": "The dispute is under review by the issuer or chargeback resolution center.", "won": "The cardholder's bank decided in your favor.", "lost": "The cardholder's bank decided in favor of the cardholder." } }, "DisputeReason": { "type": "string", "enum": [ "credit_not_processed", "duplicate", "fraudulent", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized", "authorization_error", "incorrect_amount", "late_presentment", "paid_by_other_means", "general" ], "description": "The cardholder's stated reason for dispute.", "x-enum-descriptions": { "authorization_error": "The transaction was not properly authorized or the authorization was declined.", "credit_not_processed": "The cardholder claims they were entitled to a refund they did not receive.", "duplicate": "The cardholder claims the charge is a duplicate of a previous charge.", "fraudulent": "The cardholder claims they did not authorize the charge.", "general": "All other reasons not covered by the other categories.", "incorrect_amount": "The cardholder claims the amount charged is incorrect or has been altered.", "late_presentment": "The transaction was not presented to the cardholder's bank within the required timeframe.", "paid_by_other_means": "The cardholder claims they already paid for the transaction by other means.", "product_not_received": "The cardholder claims they did not receive the product or service.", "product_unacceptable": "The cardholder claims the product or service is unacceptable, defective, or not as described.", "subscription_canceled": "The cardholder claims they canceled their subscription, but were charged anyway.", "unrecognized": "The cardholder claims they do not recognize the charge." } }, "File": { "type": "object", "properties": { "object": { "type": "string", "const": "file", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "name": { "type": "string", "description": "The name of the file." }, "purpose": { "description": "The file’s intented use.", "$ref": "#/components/schemas/FilePurpose" }, "size": { "type": "integer", "description": "The size of the file in bytes." } }, "required": [ "object", "live", "id", "created_at", "name", "purpose", "size" ], "additionalProperties": false, "example": { "object": "file", "live": false, "id": "file_nwjUEfzvIm7skTF9hlH4P2", "created_at": 1750000000000, "name": "receipt.png", "purpose": "dispute_evidence", "size": 1024 } }, "FilePurpose": { "type": "string", "enum": [ "dispute_evidence", "invoice_attachment", "product_image" ] }, "Invoice": { "type": "object", "properties": { "object": { "type": "string", "const": "invoice", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "billing_address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The billing address for the invoice." }, "customer": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Customer" } ], "x-expandable": true, "description": "Expandable. The customer associated with the invoice." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "payments": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, { "type": "null" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The payments associated with the invoice." }, "line_items": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, { "type": "null" } ], "description": "Expandable. The line items included in this invoice." }, "number": { "type": "string", "description": "The invoice number." }, "shipping_details": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient's name." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient's phone number." }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "Shipping address for the invoice." } }, "required": [ "name", "phone", "address" ], "additionalProperties": false }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "due_date": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The due date for the invoice as a Unix timestamp in milliseconds." }, "days_until_due": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of days until the invoice is due. When the invoice is finalized, this will be used to calculate the due_date if set." }, "default_taxes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "The tax percentage out of 100." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The display name for the tax (e.g., 'CA Sales Tax')." } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, { "type": "null" } ], "description": "The default taxes used for line items without their own taxes." }, "subtotal": { "type": "integer", "description": "The amount of the invoice after discounts and before taxes." }, "total_taxes": { "type": "integer", "description": "The total amount of taxes on the invoice." }, "total": { "type": "integer", "description": "The total amount of the invoice after discounts and taxes." }, "amount_due": { "type": "integer", "description": "The amount owed on the invoice, net of any issued credit notes. Set when the invoice is finalized and does not decrease as payments are made; use `amount_paid` to track payments." }, "amount_paid": { "type": "integer", "description": "The amount that has been paid on this invoice." }, "external_sync": { "anyOf": [ { "$ref": "#/components/schemas/ExternalSync" }, { "type": "null" } ], "description": "The external system record linked to this invoice, if any." }, "attachments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, { "type": "null" } ], "x-expandable": true, "description": "Expandable. Files related to the invoice that are shown to the customer." }, "credit_notes": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, { "type": "null" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The credit notes issued against this invoice." }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal memo for the invoice." }, "footer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Footer text displayed on the invoice." }, "custom_fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Custom fields for the invoice." }, "payment_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A link to a payment page for this invoice." } }, "required": [ "object", "live", "id", "created_at", "updated_at", "billing_address", "customer", "metadata", "payments", "line_items", "number", "shipping_details", "status", "due_date", "days_until_due", "default_taxes", "subtotal", "total_taxes", "total", "amount_due", "amount_paid", "external_sync", "attachments", "credit_notes", "memo", "footer", "custom_fields", "payment_link" ], "additionalProperties": false, "example": { "object": "invoice", "live": false, "id": "inv_2bA3FSNtE8Qmpg2ufwPmC2", "created_at": 1750000000000, "updated_at": 1750000000000, "billing_address": null, "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "due_date": 1750086400000, "days_until_due": null, "payments": [], "line_items": [], "metadata": {}, "number": "INV-001", "shipping_details": { "name": "John Doe", "phone": "+1 (555) 123-4567", "address": { "line1": "123 Hope St", "line2": null, "city": "Los Angeles", "state": "CA", "postal_code": "94111", "country": "US" } }, "status": "open", "default_taxes": [], "subtotal": 2000, "total_taxes": 0, "total": 2000, "amount_due": 2000, "amount_paid": 0, "external_sync": null, "attachments": [], "credit_notes": null, "memo": null, "footer": null, "custom_fields": null, "payment_link": null } }, "Address": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The city of the address." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The state or province of the address." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The postal or ZIP code of the address." }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ], "description": "The country of the address." } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "additionalProperties": false, "example": { "line1": "123 Main St", "line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94111", "country": "US" } }, "LineItem": { "type": "object", "properties": { "object": { "type": "string", "const": "line_item", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "type": { "$ref": "#/components/schemas/LineItemType" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of this product being purchased." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name for this line item when not backed by a catalog price." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional descriptive text for this line item." }, "unit_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The unit amount in cents for this line item when it is not backed by a catalog price." }, "price": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Price" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The catalog price backing this line item, if any." }, "discounts": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Discount" } }, { "type": "null" } ], "x-expandable": true, "description": "Expandable. The discounts applied to this line item." }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "The tax percentage out of 100." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The display name for the tax (e.g., 'CA Sales Tax')." } }, "required": [ "percentage", "display_name" ], "additionalProperties": false }, "description": "The taxes applied to this line item." }, "subtotal": { "type": "integer", "description": "The subtotal amount in cents after discounts." }, "total": { "type": "integer", "description": "The total amount in cents after applying discounts and taxes." } }, "required": [ "object", "live", "id", "created_at", "updated_at", "type", "quantity", "name", "description", "unit_amount", "price", "discounts", "taxes", "subtotal", "total" ], "additionalProperties": false, "example": { "object": "line_item", "id": "li_rbw8iroSXBkFMZ8bisSxK", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "type": "custom", "quantity": 2, "name": "Custom item", "description": "Custom consulting work", "unit_amount": 1000, "price": "price_dz1NVvl5CSogERkeA9Ng67", "discounts": [], "subtotal": 2000, "total": 2000 } }, "LineItemType": { "type": "string", "enum": [ "custom", "catalog" ], "description": "Discriminates how this line item is priced.", "x-enum-descriptions": { "custom": "A one-off line item with an inline name and unit_amount, not backed by a catalog price.", "catalog": "A line item backed by a catalog price." } }, "Price": { "type": "object", "properties": { "object": { "type": "string", "const": "price", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the price has been deleted." }, "product": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Product" } ], "x-expandable": true, "description": "The product that this price is attached to." }, "active": { "type": "boolean", "description": "Whether the price can be used for new purchases." }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "A short description of the price for internal use. Price descriptions are not shown to customers." }, "amount": { "type": "integer", "minimum": 0, "description": "The price in cents" }, "type": { "type": "string", "enum": [ "one_time" ], "description": "The price type." }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "updated_at", "deleted", "product", "active", "description", "amount", "type", "metadata" ], "additionalProperties": false, "example": { "object": "price", "id": "price_dz1NVvl5CSogERkeA9Ng67", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "product": "prod_KDCnId9DMZSOA9MSaut4Q", "active": true, "description": "Standard price", "amount": 2999, "type": "one_time", "metadata": {} } }, "Product": { "type": "object", "properties": { "object": { "type": "string", "const": "product", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the product has been deleted." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's name." }, "description": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "An optional description of the product." }, "active": { "type": "boolean", "description": "Whether the product can be used for new purchases." }, "default_price": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Price" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The default price for this product." }, "prices": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, { "type": "null" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. All prices for this product." }, "images": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, { "type": "null" } ], "x-expandable": true, "description": "Visual media representing the product." }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "updated_at", "deleted", "name", "description", "active", "default_price", "prices", "images", "metadata" ], "additionalProperties": false, "example": { "object": "product", "id": "prod_KDCnId9DMZSOA9MSaut4Q", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "Cosmos", "description": "Light roast coffee beans", "active": true, "default_price": null, "prices": null, "images": [], "metadata": {} } }, "Discount": { "type": "object", "properties": { "object": { "type": "string", "const": "discount", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the discount has been deleted." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The discount’s name as shown to customers." }, "amount_off": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "The flat rate discount amount in cents" }, "percent_off": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "The percentage discount amount (e.g. 15 for 15%)" }, "promotion_code": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "Customer-redeemable code that can be used to apply this coupon to an order." }, "applies_to": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, { "type": "null" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The products this discount applies to. When null, applies to all products." }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "updated_at", "deleted", "name", "amount_off", "percent_off", "promotion_code", "applies_to", "metadata" ], "additionalProperties": false, "example": { "object": "discount", "id": "disc_0yejjs3V3DfgTCMZdtKIu7", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "10% off", "amount_off": null, "percent_off": 10, "promotion_code": "SAVE10", "applies_to": null, "metadata": {} } }, "InvoiceStatus": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible", "void" ], "description": "The status of the invoice.", "x-enum-descriptions": { "draft": "The invoice is in draft state and has not been finalized.", "open": "The invoice has been finalized and is awaiting payment.", "paid": "The invoice has been paid in full.", "uncollectible": "The invoice has been marked as uncollectible.", "void": "The invoice has been voided and is no longer valid." } }, "CreditNote": { "type": "object", "properties": { "object": { "type": "string", "const": "credit_note", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "updated_at": { "type": "integer", "description": "Time at which the object was last updated. Measured in milliseconds since the Unix epoch." }, "invoice": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Invoice" } ], "x-expandable": true, "description": "Expandable. The invoice this credit note credits." }, "status": { "$ref": "#/components/schemas/CreditNoteStatus" }, "line_items": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteLineItem" } }, { "type": "null" } ], "description": "Expandable. The line items included in this credit note." }, "subtotal": { "type": "integer", "description": "The sum of the credit note line item pre-tax amounts." }, "total_taxes": { "type": "integer", "description": "The total amount of taxes on the credit note." }, "total": { "type": "integer", "description": "The total amount credited to the invoice, including taxes." }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional memo describing the credit note." }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "object", "live", "id", "created_at", "updated_at", "invoice", "status", "line_items", "subtotal", "total_taxes", "total", "memo", "metadata" ], "additionalProperties": false, "example": { "object": "credit_note", "live": false, "id": "cn_hxUznDJdC6eOs4OcqeVP83", "created_at": 1750000000000, "updated_at": 1750000000000, "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2", "status": "issued", "line_items": [], "subtotal": 10000, "total_taxes": 875, "total": 10875, "memo": null, "metadata": {} } }, "CreditNoteStatus": { "type": "string", "enum": [ "issued", "void" ], "description": "The status of the credit note.", "x-enum-descriptions": { "issued": "The credit note has been issued and reduces the invoice's net balance.", "void": "The credit note has been voided and no longer affects the invoice." } }, "CreditNoteLineItem": { "type": "object", "properties": { "object": { "type": "string", "const": "credit_note_line_item", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "name": { "type": "string", "description": "The display name for this credit note line item." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional descriptive text for this credit note line item." }, "unit_amount": { "type": "integer", "description": "The pre-tax unit amount in cents being credited. Always positive." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity being credited." }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "The tax percentage out of 100." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The display name for the tax (e.g., 'CA Sales Tax')." } }, "required": [ "percentage", "display_name" ], "additionalProperties": false }, "description": "The taxes applied to this credit note line item." }, "subtotal": { "type": "integer", "description": "The pre-tax subtotal in cents (unit_amount × quantity)." }, "total": { "type": "integer", "description": "The total in cents after applying taxes." } }, "required": [ "object", "id", "name", "description", "unit_amount", "quantity", "taxes", "subtotal", "total" ], "additionalProperties": false, "example": { "object": "credit_note_line_item", "id": "cnli_GHkHeA2p80fum3yG9mbpc3", "name": "Refund: consulting", "description": null, "unit_amount": 10000, "quantity": 1, "taxes": [ { "percentage": 8.75, "display_name": "CA Sales Tax" } ], "subtotal": 10000, "total": 10875 } }, "SessionMode": { "type": "string", "enum": [ "payment", "setup" ], "description": "The mode of the session determines if payment methods are saved and when the customer is charged.", "x-enum-descriptions": { "payment": "Charge a customer for a one-time payment.", "setup": "Set up a customer’s payment method for future use." } }, "SessionStatus": { "type": "string", "enum": [ "open", "expired", "complete" ], "description": "The status of the session.", "x-enum-descriptions": { "complete": "The customer has successfully completed the checkout process. One or more successful payments have fulfilled the session’s target `amount`.", "expired": "The session has expired. The customer will need to start over with a new session.", "open": "The session is open. The customer has not yet completed the checkout process." } }, "SessionSubmitLabel": { "type": "string", "enum": [ "auto", "book", "donate", "pay", "subscribe" ], "description": "Specify the submit intent for the session. Used to adjust the text on Checkout components to reflect the type of purchase.", "x-enum-descriptions": { "auto": "Automatically select a submit intent.", "book": "The customer is booking an appointment.", "donate": "The customer is donating to a cause.", "pay": "The customer is paying for a product or service.", "subscribe": "The customer is subscribing to a service." } }, "CheckoutSessionFilters": { "type": "object", "properties": { "amount": { "description": "Filter by the checkout session's amount.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "created_at": { "description": "Filter by the checkout session's creation date.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "customer": { "description": "Filter by the customer's ID.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "NumberFilter": { "type": "object", "properties": { "eq": { "type": "number" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, "MetadataInput": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] }, "description": "A [key-value store](/api-reference/metadata) that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use." }, "IdempotencyError": { "type": "object", "properties": { "object": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "const": "idempotency_error" }, "live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "code": { "type": "null", "const": null }, "message": { "type": "string" }, "param": { "type": "null", "const": null } }, "required": [ "type", "live", "code", "message", "param" ], "additionalProperties": false } }, "required": [ "object", "error" ], "additionalProperties": false }, "CreditNoteFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the credit note's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "updated_at": { "description": "Filter by the credit note's last update date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "invoice": { "description": "Filter by the invoice the credit note credits", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "description": "Filter by credit note status", "anyOf": [ { "$ref": "#/components/schemas/CreditNoteStatus" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/CreditNoteStatus" }, "neq": { "$ref": "#/components/schemas/CreditNoteStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/CreditNoteStatus" }, "neq": { "$ref": "#/components/schemas/CreditNoteStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "CustomerFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the customer’s creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "email": { "description": "Filter by the customer’s email", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "name": { "description": "Filter by the customer’s name", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "phone": { "description": "Filter by the customer’s phone number", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "StringFilter": { "type": "object", "properties": { "eq": { "type": "string" }, "contains": { "type": "string" }, "starts_with": { "type": "string" }, "ends_with": { "type": "string" }, "case_sensitive": { "type": "boolean" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, "DiscountFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the discount's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "name": { "description": "Filter by the discount's name", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "promotion_code": { "description": "Filter by the discount's promotion code", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "applies_to": { "description": "Filter by product ID that the discount applies to", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "DisputeFilters": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "amount": { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "payment": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "anyOf": [ { "$ref": "#/components/schemas/DisputeStatus" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/DisputeStatus" }, "neq": { "$ref": "#/components/schemas/DisputeStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/DisputeStatus" }, "neq": { "$ref": "#/components/schemas/DisputeStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "EventExpand": { "type": "object", "properties": { "request": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/RequestExpand" } ] } }, "additionalProperties": false }, "RequestExpand": { "type": "object", "properties": { "api_key": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/ApiKeyExpand" } ] }, "dashboard_user": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/DashboardUserExpand" } ] } }, "additionalProperties": false }, "ApiKeyExpand": { "type": "object", "properties": {}, "additionalProperties": false }, "DashboardUserExpand": { "type": "object", "properties": { "merchants": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/MerchantExpand" } ] }, "organizations": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/OrganizationExpand" } ] } }, "additionalProperties": false }, "MerchantExpand": { "type": "object", "properties": { "settings": { "type": "boolean" } }, "additionalProperties": false }, "OrganizationExpand": { "type": "object", "properties": { "merchants": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/MerchantExpand" } ] } }, "additionalProperties": false }, "Event": { "type": "object", "properties": { "object": { "type": "string", "const": "event", "description": "Literal representing the object’s type." }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "previous_state": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/CheckoutSession" }, { "$ref": "#/components/schemas/CreditNote" }, { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/Discount" }, { "$ref": "#/components/schemas/Dispute" }, { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/Payment" }, { "$ref": "#/components/schemas/PaymentMethod" }, { "$ref": "#/components/schemas/Price" }, { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/Refund" } ] }, { "type": "null" } ], "description": "The full object state before the event occurred." }, "state": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/CheckoutSession" }, { "$ref": "#/components/schemas/CreditNote" }, { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/Discount" }, { "$ref": "#/components/schemas/Dispute" }, { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/Payment" }, { "$ref": "#/components/schemas/PaymentMethod" }, { "$ref": "#/components/schemas/Price" }, { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/Refund" } ] }, { "type": "null" } ], "description": "The full object state after the event occurred." }, "request": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Request" } ], "x-expandable": true }, { "type": "null" } ], "description": "Expandable. The request, if any, that triggered the event." }, "type": { "$ref": "#/components/schemas/EventType" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/EventContext" }, { "type": "null" } ], "description": "System-generated context describing the circumstances of the event, if any." } }, "required": [ "object", "live", "id", "created_at", "previous_state", "state", "request", "type", "context" ], "additionalProperties": false, "example": { "object": "event", "live": false, "id": "event_I4WDb42QLgdAVoESZlGJY3", "created_at": 1750000000000, "state": { "object": "customer", "id": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "John Doe", "email": "john@bias.dev", "phone": null, "external_sync": null, "metadata": {} }, "previous_state": null, "request": "req_N6uUqAC2SFJmLKvAQbcEn3", "type": "customer.created", "context": null } }, "Refund": { "type": "object", "properties": { "object": { "type": "string", "const": "refund", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "amount": { "type": "integer", "description": "The amount refunded." }, "failed_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "If `status` is `failed`, contains a message explaining why the refund failed." }, "payment": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Payment" } ], "x-expandable": true, "description": "Expandable. The payment being refunded." }, "status": { "$ref": "#/components/schemas/RefundStatus" } }, "required": [ "object", "id", "live", "created_at", "amount", "failed_reason", "payment", "status" ], "additionalProperties": false, "example": { "object": "refund", "id": "re_3UgC74NSEMIWiFK5s3tZ82", "live": false, "created_at": 1750000000000, "amount": 1000, "failed_reason": null, "payment": "pay_lUY2g0TuPzN9qi4couahd3", "status": "succeeded" } }, "RefundStatus": { "type": "string", "enum": [ "failed", "pending", "succeeded" ], "description": "The status of the refund.", "x-enum-descriptions": { "succeeded": "The refund was successfully processed.", "pending": "The refund is pending.", "failed": "The refund failed. See `failed_reason` for details." } }, "Request": { "type": "object", "properties": { "object": { "type": "string", "const": "request", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "live": { "type": "boolean", "description": "Has the value `true` if the object exists in a production environment or the value `false` if the object exists in a sandbox environment." }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "resource_path": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "request": { "type": "object", "properties": { "body": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "ip": { "type": "string" } }, "required": [ "body", "headers", "ip" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "body": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "body", "headers", "status" ], "additionalProperties": false }, "api_key": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ApiKey" } ], "x-expandable": true }, { "type": "null" } ] }, "dashboard_user": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/DashboardUser" } ], "x-expandable": true }, { "type": "null" } ] } }, "required": [ "object", "id", "live", "created_at", "method", "url", "resource_path", "request", "response", "api_key", "dashboard_user" ], "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "object": { "type": "string", "const": "api_key", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "live": { "type": "boolean" }, "active": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "object", "id", "created_at", "live", "active", "description" ], "additionalProperties": false }, "DashboardUser": { "type": "object", "properties": { "object": { "type": "string", "const": "dashboard_user", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "email": { "type": "string" }, "merchants": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Merchant" } }, { "type": "null" } ], "x-expandable": true }, "organizations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "entitlements": { "type": "array", "items": { "type": "string" } }, "impersonating": { "type": "boolean" } }, "required": [ "object", "id", "created_at", "email", "merchants", "organizations", "name", "phone", "entitlements" ], "additionalProperties": false }, "Merchant": { "type": "object", "properties": { "object": { "type": "string", "const": "merchant", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the merchant has been deleted." }, "live": { "type": "boolean" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "available_payment_method_types": { "type": "array", "items": { "type": "string", "enum": [ "card", "us_bank_account" ], "description": "The type of the payment method.", "x-enum-descriptions": { "card": "Credit or debit card.", "us_bank_account": "US bank account (ACH)." } }, "description": "The payment method types available to this merchant. Controls which types can be enabled in merchant settings." }, "settings": { "description": "The merchant's public and payment settings.", "anyOf": [ { "$ref": "#/components/schemas/MerchantSettings" }, { "type": "null" } ] } }, "required": [ "object", "id", "created_at", "deleted", "live", "name", "active", "available_payment_method_types" ], "additionalProperties": false }, "MerchantSettings": { "type": "object", "properties": { "object": { "type": "string", "const": "merchant_settings", "description": "Literal representing the object’s type." }, "merchant_id": { "description": "The ID of the merchant these settings belong to.", "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "contact_email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "description": "The merchant's contact email address." }, "contact_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The merchant's contact phone number." }, "statement_descriptor": { "anyOf": [ { "type": "string", "maxLength": 22 }, { "type": "null" } ], "description": "The statement descriptor that appears on customer's credit card statements." }, "invoice_number_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The prefix for invoice numbers." }, "invoice_number_counter": { "type": "integer", "description": "The counter for invoice numbers." }, "invoice_terms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The default terms for invoices." }, "default_dual_pricing_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The default dual pricing rate for newly created invoices, expressed as a percentage. For example, `3` represents 3%." }, "accent_color": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ], "description": "The merchant's accent color (hex code)." }, "brand_color": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ], "description": "The merchant's brand color (hex code)." }, "brand_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The merchant's brand logo file ID." }, "brand_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The merchant's brand icon file ID." }, "invoices": { "type": "object", "properties": { "fonts": { "type": "object", "properties": { "display": { "type": "string", "enum": [ "Inter", "DM Sans", "Lato", "Public Sans", "Open Sans", "Plus Jakarta Sans", "Work Sans", "Source Sans 3", "Poppins", "Manrope", "Lora", "Libre Baskerville", "Merriweather", "Source Serif 4", "Spectral", "Fira Mono", "IBM Plex Mono", "JetBrains Mono", "Roboto Mono", "Source Code Pro" ], "description": "Font family for invoice headings and titles" }, "body": { "type": "string", "enum": [ "Inter", "DM Sans", "Lato", "Public Sans", "Open Sans", "Plus Jakarta Sans", "Work Sans", "Source Sans 3", "Poppins", "Manrope", "Lora", "Libre Baskerville", "Merriweather", "Source Serif 4", "Spectral", "Fira Mono", "IBM Plex Mono", "JetBrains Mono", "Roboto Mono", "Source Code Pro" ], "description": "Font family for invoice body text" } }, "required": [ "display", "body" ], "additionalProperties": false } }, "required": [ "fonts" ], "additionalProperties": false, "description": "Invoice customization settings" }, "enabled_payment_method_types": { "type": "array", "items": { "type": "string", "enum": [ "card", "us_bank_account" ], "description": "The type of the payment method.", "x-enum-descriptions": { "card": "Credit or debit card.", "us_bank_account": "US bank account (ACH)." } }, "description": "The payment method types enabled for checkout sessions. Checkout sessions created by this merchant will default to these types." } }, "required": [ "object", "merchant_id", "address", "contact_email", "contact_phone", "statement_descriptor", "invoice_number_prefix", "invoice_number_counter", "invoice_terms", "default_dual_pricing_rate", "accent_color", "brand_color", "brand_logo", "brand_icon", "invoices", "enabled_payment_method_types" ], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "object": { "type": "string", "const": "organization", "description": "Literal representing the object’s type." }, "id": { "description": "Unique identifier for the object.", "type": "string" }, "created_at": { "type": "integer", "description": "Time at which the object was created. Measured in milliseconds since the Unix epoch." }, "deleted": { "type": "boolean", "description": "Whether the organization has been deleted." }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "object", "id", "created_at", "deleted", "name", "active" ], "additionalProperties": false }, "EventType": { "type": "string", "enum": [ "customer.created", "customer.updated", "customer.deleted", "payment.created", "payment.updated", "payment.amount_capturable_updated", "payment.succeeded", "payment.canceled", "payment.failed", "payment_method.created", "payment_method.updated", "payment_method.deactivated", "refund.created", "refund.succeeded", "refund.failed", "file.created", "file.updated", "dispute.created", "dispute.updated", "checkout_session.created", "checkout_session.updated", "checkout_session.completed", "checkout_session.expired", "product.created", "product.updated", "product.deleted", "price.created", "price.updated", "discount.created", "discount.updated", "discount.deleted", "invoice.created", "invoice.updated", "invoice.deleted", "invoice.finalized", "invoice.sent", "invoice.reminder_sent", "invoice.voided", "invoice.paid", "invoice.payment_failed", "invoice.marked_uncollectible", "credit_note.created", "credit_note.updated", "credit_note.sent", "credit_note.voided" ], "description": "The type of event that occurred. Follows the format of `object.action`." }, "EventContext": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.sent" }, "recipient_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "The email address the invoice was sent to." } }, "required": [ "type", "recipient_email" ], "additionalProperties": false } ], "description": "System-generated context describing the circumstances of an event." }, "EventFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the event's creation date.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "for": { "description": "ID of a resource. Filter by event that pertain to a specific resource.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "object": { "description": "Filter by the event's object type, e.g. `customer`.", "anyOf": [ { "$ref": "#/components/schemas/EventObjectType" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/EventObjectType" }, "neq": { "$ref": "#/components/schemas/EventObjectType" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/EventObjectType" }, "neq": { "$ref": "#/components/schemas/EventObjectType" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "type": { "description": "Filter by the event's type.", "anyOf": [ { "$ref": "#/components/schemas/EventType" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/EventType" }, "neq": { "$ref": "#/components/schemas/EventType" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/EventType" }, "neq": { "$ref": "#/components/schemas/EventType" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "EventObjectType": { "type": "string", "enum": [ "customer", "payment", "payment_method", "refund", "file", "dispute", "checkout_session", "product", "price", "discount", "invoice", "credit_note" ], "description": "The type of object that the event pertains to." }, "FileFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the file's creation date.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "size": { "description": "Filter by the file's size.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "purpose": { "description": "Filter by the file's purpose.", "anyOf": [ { "$ref": "#/components/schemas/FilePurpose" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/FilePurpose" }, "neq": { "$ref": "#/components/schemas/FilePurpose" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/FilePurpose" }, "neq": { "$ref": "#/components/schemas/FilePurpose" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "InvoiceFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the invoices's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "updated_at": { "description": "Filter by the invoices's last update date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "due_date": { "description": "Filter by the invoice's due date as a Unix timestamp in milliseconds", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "customer": { "description": "Filter by customer ID", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "description": "Filter by invoice status", "anyOf": [ { "$ref": "#/components/schemas/InvoiceStatus" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/InvoiceStatus" }, "neq": { "$ref": "#/components/schemas/InvoiceStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/InvoiceStatus" }, "neq": { "$ref": "#/components/schemas/InvoiceStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "PaymentMethodFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the payment method's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "customer": { "description": "Filter by the customer associated with the payment method", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "active": { "description": "Filter by the payment method's active status", "$ref": "#/components/schemas/BooleanFilter" } }, "additionalProperties": false }, "BooleanFilter": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "eq": { "type": "boolean" } }, "additionalProperties": false } ] }, "PaymentError": { "type": "object", "properties": { "object": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "type": { "type": "string", "const": "payment_error" }, "live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "code": { "type": "null", "const": null }, "decline_code": { "anyOf": [ { "$ref": "#/components/schemas/PaymentDeclineCode" }, { "type": "null" } ] }, "network_decline_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/Payment" }, { "type": "null" } ] } }, "required": [ "type", "live", "code", "decline_code", "network_decline_code", "message", "param", "payment" ], "additionalProperties": false } }, "required": [ "object", "error" ], "additionalProperties": false }, "PaymentFilters": { "type": "object", "properties": { "amount": { "description": "Filter by the payment’s amount.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "amount_received": { "description": "Filter by the amount received.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "amount_refunded": { "description": "Filter by the amount refunded.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "created_at": { "description": "Filter by the payment’s creation date.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "customer": { "description": "Filter by the payment’s customer.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "disputed": { "description": "Filter by whether the payment is disputed.", "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "eq": { "type": "boolean" }, "neq": { "type": "boolean" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "boolean" }, "neq": { "type": "boolean" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "invoice": { "description": "Filter by the payment’s invoice.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "session": { "description": "Filter by the payment’s checkout session.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "description": "Filter by the payment’s status.", "anyOf": [ { "$ref": "#/components/schemas/PaymentStatus" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/PaymentStatus" }, "neq": { "$ref": "#/components/schemas/PaymentStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/PaymentStatus" }, "neq": { "$ref": "#/components/schemas/PaymentStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "PriceFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the price's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "product": { "description": "Filter by the price's product ID", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "active": { "description": "Filter by the price's active status", "$ref": "#/components/schemas/BooleanFilter" }, "amount": { "description": "Filter by the price's amount", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "description": { "description": "Filter by the price's description", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "ProductFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the product's creation date", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "name": { "description": "Filter by the product's name", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "description": { "description": "Filter by the product's description", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "active": { "description": "Filter by the product's active status", "$ref": "#/components/schemas/BooleanFilter" } }, "additionalProperties": false }, "RefundExpand": { "type": "object", "properties": { "payment": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/PaymentExpand" } ] } }, "additionalProperties": false }, "RefundFilters": { "type": "object", "properties": { "created_at": { "description": "Filter by the refund's creation date.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "amount": { "description": "Filter by the refund's amount.", "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "payment": { "description": "Filter by the payment being refunded.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "payment_method": { "description": "Filter by the payment method used to make the payment.", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "description": "Filter by the refund's status.", "anyOf": [ { "$ref": "#/components/schemas/RefundStatus" }, { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/RefundStatus" }, "neq": { "$ref": "#/components/schemas/RefundStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "$ref": "#/components/schemas/RefundStatus" }, "neq": { "$ref": "#/components/schemas/RefundStatus" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "StatisticQuery": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "payment" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/PaymentFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PaymentFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "amount" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "customer" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/CustomerFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CustomerFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "dispute" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/DisputeFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DisputeFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "amount" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "refund" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/RefundFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RefundFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RefundFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RefundFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "amount" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "invoice" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/InvoiceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "total", "subtotal", "amount_paid", "due_date" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "product" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/ProductFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ProductFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "event" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/EventFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/EventFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EventFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/EventFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "request" }, "filters": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/RequestFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RequestFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RequestFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RequestFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] }, "aggregation": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at" ] }, "type": { "$ref": "#/components/schemas/StatisticAggregationType" } }, "required": [ "field", "type" ], "additionalProperties": false }, "group_by": { "type": "object", "properties": { "time": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StatisticTimeInterval" }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "fill_missing": { "default": "zero", "type": "string", "enum": [ "zero", "null", "previous" ] } }, "required": [ "object", "aggregation" ], "additionalProperties": false } ] }, "StatisticAggregationType": { "type": "string", "enum": [ "sum", "average", "count", "min", "max", "median", "percentile_95", "percentile_99" ], "x-enum-descriptions": { "sum": "Sum", "average": "Average", "min": "Minimum", "max": "Maximum", "count": "Count", "median": "Median (50th percentile)", "percentile_95": "95th percentile", "percentile_99": "99th percentile" } }, "StatisticTimeInterval": { "type": "string", "enum": [ "1m", "5m", "10m", "15m", "30m", "1h", "2h", "4h", "6h", "12h", "1d", "1w", "1M", "1q", "1y" ], "x-enum-descriptions": { "1m": "1 minute", "5m": "5 minutes", "10m": "10 minutes", "15m": "15 minutes", "30m": "30 minutes", "1h": "1 hour", "2h": "2 hours", "4h": "4 hours", "6h": "6 hours", "12h": "12 hours", "1d": "1 day", "1w": "1 week", "1M": "1 month", "1q": "1 quarter", "1y": "1 year" } }, "RequestFilters": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "url": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StringFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/StringFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] }, "method": { "anyOf": [ { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, { "type": "object", "properties": { "eq": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "neq": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "neq": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "dashboard_user": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "properties": { "or": { "type": "array", "items": { "type": "object", "properties": { "eq": { "type": "string" }, "neq": { "type": "string" }, "exists": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "or" ], "additionalProperties": false } ] }, "status": { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/NumberFilter" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/NumberFilter" } } }, "required": [ "or" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "Stats": { "type": "object", "properties": { "object": { "type": "string", "const": "stats" }, "stats": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "integer", "description": "Start time of the interval if using `group_by`. Measured in milliseconds since the Unix epoch." }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "value" ], "additionalProperties": false } } } }, "required": [ "object", "stats" ], "additionalProperties": false } } }, "paths": { "/v1/checkout/sessions/{id}/public_key": { "get": { "description": "Get the RSA-OAEP public key for a checkout session", "x-path": [ "checkout", "sessions", "public_key" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "The RSA-OAEP 4096-bit public key (SPKI, base64-encoded) for this checkout session." } }, "required": [ "public_key" ], "additionalProperties": false } } }, "description": "RSA-OAEP public key for the checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Checkout session does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/checkout/sessions/{id}": { "get": { "description": "Get a checkout session", "x-path": [ "checkout", "sessions", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/CheckoutSessionExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "Retrieved checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Checkout session does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a checkout session", "x-path": [ "checkout", "sessions", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/CheckoutSessionExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "line_items": { "description": "The line items representing what is being purchased", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "ID of existing line item to keep or update", "type": "string" }, "price": { "description": "The ID of the price to use for this line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "description": "The quantity of the line item.", "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001 }, { "type": "null" } ] }, "discounts": { "description": "An array of discount IDs to apply to this line item.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, { "type": "object", "properties": { "price": { "description": "The ID of the price to use for this line item.", "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of the line item." }, "discounts": { "description": "An array of discount IDs to apply to this line item.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "price", "quantity" ], "additionalProperties": false } ] } }, "customer": { "description": "The customer's associated with the session.", "type": "string" }, "customer_details": { "description": "The customer’s details entered in this session. When the session completes, the created customer will inherit these values.", "type": "object", "properties": { "email": { "description": "The customer‘s email address.", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "name": { "description": "The customer‘s full name or business name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "The customer‘s phone number.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "dual_pricing": { "description": "Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is.", "anyOf": [ { "type": "object", "properties": { "rate": { "type": "number", "description": "The dual pricing rate as a percentage. For example, `3` represents 3%. This rate is applied only when the payment method type is `card`." } }, "required": [ "rate" ], "additionalProperties": false }, { "type": "null" } ] }, "metadata": { "description": "A [key-value store](/api-reference/metadata) that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use.", "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "line_items": [ { "id": "li_rbw8iroSXBkFMZ8bisSxK", "quantity": 3 }, { "price": "price_dz1NVvl5CSogERkeA9Ng67", "quantity": 1 } ], "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "Updated checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Session does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/checkout/sessions": { "get": { "description": "List all checkout sessions", "x-path": [ "checkout", "sessions", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/CheckoutSessionExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "checkout_session", "id": "cs_MyJuJvswjRM54vPXr6qBh2", "live": false, "created_at": 1750000000000, "amount": 1000, "amount_collected": 1000, "dual_pricing": null, "client_details": null, "client_secret": "uEyLI6rmFylTwIBik5cpn8ge", "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "customer_details": { "email": null, "name": null, "phone": null }, "payments": [], "invoice": null, "line_items": [], "metadata": {}, "mode": "payment", "payment_method_types": [ "card", "us_bank_account" ], "status": "complete", "submit_label": "auto" }, "has_more": false } } } }, "description": "List of checkout sessions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "post": { "description": "Create a checkout session", "x-path": [ "checkout", "sessions", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/CheckoutSessionExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Amount in cents for this session. Mutually exclusive with line_items and invoice.", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "line_items": { "description": "The line items representing the products or services being purchased.", "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "price": { "description": "The ID of the price to use for this line item.", "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of the line item." }, "discounts": { "description": "An array of discount IDs to apply to this line item.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "price", "quantity" ], "additionalProperties": false } }, { "type": "null" } ] }, "customer": { "description": "Expandable. The customer associated with the checkout session.", "type": "string" }, "customer_details": { "description": "The customer’s details entered in this session. When the session completes, the created customer will inherit these values.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "invoice": { "description": "Expandable. The invoice this checkout session was created from.", "type": "string" }, "dual_pricing": { "description": "Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is.", "anyOf": [ { "type": "object", "properties": { "rate": { "type": "number", "description": "The dual pricing rate as a percentage. For example, `3` represents 3%. This rate is applied only when the payment method type is `card`." } }, "required": [ "rate" ], "additionalProperties": false }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] }, "mode": { "default": "payment", "$ref": "#/components/schemas/SessionMode" }, "payment_method_types": { "description": "The payment method types to accept for this session. Defaults to the merchant's enabled_payment_method_types setting.", "type": "array", "items": { "type": "string", "enum": [ "card", "us_bank_account" ], "description": "The type of the payment method.", "x-enum-descriptions": { "card": "Credit or debit card.", "us_bank_account": "US bank account (ACH)." } } }, "submit_label": { "default": "auto", "$ref": "#/components/schemas/SessionSubmitLabel" } }, "additionalProperties": false, "example": { "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "line_items": [ { "price": "price_dz1NVvl5CSogERkeA9Ng67", "quantity": 2 } ] } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "Created checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/checkout/sessions/{id}/expire": { "post": { "description": "Expire a checkout session", "x-path": [ "checkout", "sessions", "expire" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } }, "description": "Expired checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Checkout session does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/credit_notes": { "post": { "description": "Create a credit note", "x-path": [ "credit_notes", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/CreditNoteExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "description": "The invoice this credit note credits.", "type": "string" }, "line_items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The display name for this credit note line item." }, "description": { "description": "Optional descriptive text for this credit note line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit_amount": { "type": "integer", "minimum": 0, "description": "The pre-tax unit amount in cents being credited. Must be non-negative." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity being credited." }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the credit note's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } } }, "required": [ "name", "unit_amount", "quantity" ], "additionalProperties": false }, "description": "The line items for this credit note." }, "default_taxes": { "description": "Default taxes to apply to all line items that don't specify their own taxes.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "memo": { "description": "An optional memo describing the credit note.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "required": [ "invoice", "line_items" ], "additionalProperties": false, "example": { "invoice": "inv_abc123", "line_items": [ { "name": "Refund: consulting", "unit_amount": 10000, "quantity": 1, "taxes": [ { "percentage": 8.75, "display_name": "CA Sales Tax" } ] } ] } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } }, "description": "Created credit note" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List credit notes", "x-path": [ "credit_notes", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/CreditNoteExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/CreditNoteFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CreditNoteFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "credit_note", "live": false, "id": "cn_hxUznDJdC6eOs4OcqeVP83", "created_at": 1750000000000, "updated_at": 1750000000000, "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2", "status": "issued", "line_items": [], "subtotal": 10000, "total_taxes": 875, "total": 10875, "memo": null, "metadata": {} }, "has_more": false } } } }, "description": "List of credit notes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/credit_notes/{id}": { "get": { "description": "Get a credit note", "x-path": [ "credit_notes", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/CreditNoteExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } }, "description": "Retrieved credit note" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Credit note not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a credit note", "x-path": [ "credit_notes", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/CreditNoteExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "line_items": { "description": "The line items for this credit note. Replaces all existing line items.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The display name for this credit note line item." }, "description": { "description": "Optional descriptive text for this credit note line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit_amount": { "type": "integer", "minimum": 0, "description": "The pre-tax unit amount in cents being credited. Must be non-negative." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity being credited." }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the credit note's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } } }, "required": [ "name", "unit_amount", "quantity" ], "additionalProperties": false } }, "default_taxes": { "description": "Default taxes to apply to all line items that don't specify their own taxes.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "memo": { "description": "An optional memo describing the credit note.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "memo": "Updated credit note memo" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } }, "description": "Updated credit note" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Credit note not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/credit_notes/{id}/void": { "post": { "description": "Void a credit note", "x-path": [ "credit_notes", "void" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } }, "description": "Voided credit note" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Credit note not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Credit note cannot be voided in its current status" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/customers": { "post": { "description": "Create a customer", "x-path": [ "customers", "create" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "name": { "description": "The customer‘s full name or business name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "description": "The customer‘s email address.", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "description": "The customer‘s phone number.", "anyOf": [ { "type": "string", "format": "phone", "description": "A phone number in E.164 format." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "name": "John Doe", "email": "john@bias.dev" } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "description": "Created customer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List all customers", "x-path": [ "customers", "list" ], "parameters": [ { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/CustomerFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CustomerFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "customer", "id": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "John Doe", "email": "john@bias.dev", "phone": null, "external_sync": null, "metadata": {} }, "has_more": false } } } }, "description": "List of customers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/customers/{id}": { "delete": { "description": "Delete a customer", "x-path": [ "customers", "delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "customer" }, "id": { "type": "string" }, "deleted": { "default": true, "type": "boolean", "const": true } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false, "example": { "object": "customer", "id": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "deleted": true } } } }, "description": "Deleted customer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Customer does not exist" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyError" } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "Get a customer", "x-path": [ "customers", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "description": "Retrieved customer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Customer does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a customer", "x-path": [ "customers", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The customer‘s full name or business name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "description": "The customer‘s email address.", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "description": "The customer‘s phone number.", "anyOf": [ { "type": "string", "format": "phone", "description": "A phone number in E.164 format." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "email": null, "phone": "+11234567890" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } }, "description": "Updated customer" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Customer does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/discounts": { "post": { "description": "Create a discount", "x-path": [ "discounts", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/DiscountExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The discount’s name as shown to customers." }, "amount_off": { "description": "The flat rate discount amount in cents", "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "percent_off": { "description": "The percentage discount amount (e.g. 15 for 15%)", "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, { "type": "null" } ] }, "promotion_code": { "description": "Customer-redeemable code that can be used to apply this coupon to an order.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "applies_to": { "description": "Expandable. The products this discount applies to. When null, applies to all products.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false, "example": { "name": "10% off", "percent_off": 10, "promotion_code": "SAVE10", "applies_to": null, "metadata": {} } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } }, "description": "Created discount" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List discounts", "x-path": [ "discounts", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/DiscountExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/DiscountFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DiscountFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DiscountFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DiscountFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Discount" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "discount", "id": "disc_0yejjs3V3DfgTCMZdtKIu7", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "10% off", "amount_off": null, "percent_off": 10, "promotion_code": "SAVE10", "applies_to": null, "metadata": {} }, "has_more": false } } } }, "description": "List of discounts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/discounts/{id}": { "delete": { "description": "Delete a discount", "x-path": [ "discounts", "delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "discount" }, "id": { "type": "string" }, "deleted": { "default": true, "type": "boolean", "const": true } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false, "example": { "object": "discount", "id": "disc_0yejjs3V3DfgTCMZdtKIu7", "deleted": true } } } }, "description": "Discount deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Discount not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "Get a discount", "x-path": [ "discounts", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/DiscountExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } }, "description": "Discount found" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Discount not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a discount", "x-path": [ "discounts", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/DiscountExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The discount’s name as shown to customers.", "type": "string", "minLength": 1, "maxLength": 255 }, "promotion_code": { "description": "Customer-redeemable code that can be used to apply this coupon to an order.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "name": "Summer discount", "promotion_code": "SUMMER10" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } }, "description": "Updated discount" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Discount not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/disputes/{id}": { "get": { "description": "Get a dispute", "x-path": [ "disputes", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/DisputeExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "Retrieved dispute" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Dispute does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a dispute", "x-path": [ "disputes", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/DisputeExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence": { "type": "object", "properties": { "access_activity_log": { "description": "Server or user activity logs demonstrating customer access or download of the purchased digital service or product. Include IP addresses, timestamps, and detailed recorded activity.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_address": { "description": "The billing address provided by the customer.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancellation_policy": { "description": "Expandable. Your subscription cancellation policy, as presented to the customer.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancellation_policy_disclosure": { "description": "Explanation of how and when the customer was shown your refund or cancellation policy before purchase.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancellation_rebuttal": { "description": "Justification for why the customer's subscription was not canceled.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_communication": { "description": "Expandable. Relevant communication with the customer, such as emails proving product receipt, usage, or satisfaction.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_email": { "description": "The customer's email address.", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "customer_name": { "description": "The customer's name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_purchase_ip": { "description": "The IP address used by the customer during the purchase.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_signature": { "description": "Expandable. Document or contract displaying the customer's signature.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duplicate_charge_documentation": { "description": "Expandable. Documentation uniquely identifying the prior charge, such as a receipt or shipping label. Pair with a similar document from the disputed payment to prove that transactions are separate.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duplicate_charge_explanation": { "description": "Explanation of the differences between the disputed charge and the apparent duplicate prior charge.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duplicate_payment": { "description": "The payment ID for the prior charge that appears to be a duplicate of the disputed charge.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_category": { "description": "Category of product or service purchased.", "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "physical", "digital", "offline_service", "event", "booking" ] }, { "type": "string" } ] }, { "type": "null" } ] }, "product_description": { "description": "Description of the product or service sold.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt": { "description": "Expandable. Receipt or message sent to the customer notifying them of the charge.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refund_policy": { "description": "Expandable. Your refund policy, as shown to the customer.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refund_policy_disclosure": { "description": "Documentation showing the customer was presented with your refund policy before purchase.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refund_refusal_explanation": { "description": "Justification for why the customer is not entitled to a refund.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "terms_and_conditions": { "description": "Expandable. Your terms and conditions, as presented to the customer.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "service_date": { "description": "Date the customer received or began receiving the purchased service, in a clear human-readable format.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "service_documentation": { "description": "Expandable. Proof of service provided to the customer, such as a signed contract or work order.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_address": { "description": "The address to which a physical product was shipped. Include complete address information when possible.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_carrier": { "description": "The delivery service(s) used to ship the physical product. Separate multiple carriers with commas.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_date": { "description": "Date the physical product began its route to the shipping address, in a clear human-readable format.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_documentation": { "description": "Expandable. Proof of product shipment to the customer's provided address, such as a shipment receipt or shipping label. Should show the full shipping address if possible.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_tracking_number": { "description": "Tracking number(s) for the physical product from the delivery service. Separate multiple numbers with commas.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uncategorized_file": { "description": "Expandable. Any additional evidence or statements.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uncategorized_text": { "description": "Any additional evidence or statements in text form.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "win_reason": { "description": "The reason you should win this dispute.", "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "withdrawn", "refunded", "not_fraudulent" ] }, { "type": "string" } ] }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "product_category": "physical", "shipping_tracking_number": "1Z12345E0205271688" } }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] }, "submit": { "default": false, "description": "Submit the provided dispute evidence to the cardholder’s bank. Once submitted, you will not be able to update the dispute evidence.", "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "Updated dispute" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Dispute does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/disputes": { "get": { "description": "List all disputes", "x-path": [ "disputes", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/DisputeExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "anyOf": [ { "$ref": "#/components/schemas/DisputeFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DisputeFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Dispute" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "has_more": false } } } }, "description": "List of disputes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/events/{id}": { "get": { "description": "Get a event", "x-path": [ "events", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/EventExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "description": "Retrieved event" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Event does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/events": { "get": { "description": "List or stream events", "x-path": [ "events", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/EventExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "stream", "in": "query", "schema": { "description": "Stream events matching the provided parameters as they are created. If true, the response will be a stream of events, separated by a newline. Space characters are sent periodically to keep the stream alive.", "type": "boolean" } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/EventFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/EventFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EventFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/EventFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "event", "live": false, "id": "event_I4WDb42QLgdAVoESZlGJY3", "created_at": 1750000000000, "state": { "object": "customer", "id": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "John Doe", "email": "john@bias.dev", "phone": null, "external_sync": null, "metadata": {} }, "previous_state": null, "request": "req_N6uUqAC2SFJmLKvAQbcEn3", "type": "customer.created", "context": null }, "has_more": false } } } }, "description": "List of events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/files/{id}": { "get": { "description": "Get a file", "x-path": [ "files", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/FileExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "Retrieved file" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "File does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a file", "x-path": [ "files", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the file.", "type": "string" } }, "additionalProperties": false, "example": { "name": "receipt.png" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "Updated file" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "File does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/files": { "get": { "description": "List all files", "x-path": [ "files", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/FileExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/FileFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/FileFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/FileFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/FileFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/File" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "file", "live": false, "id": "file_nwjUEfzvIm7skTF9hlH4P2", "created_at": 1750000000000, "name": "receipt.png", "purpose": "dispute_evidence", "size": 1024 }, "has_more": false } } } }, "description": "List of files" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "post": { "description": "Create a file", "x-path": [ "files", "create" ], "parameters": [], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file to upload, as binary data." }, "purpose": { "description": "The file’s intended use.", "$ref": "#/components/schemas/FilePurpose" } }, "required": [ "file", "purpose" ], "additionalProperties": false, "example": { "file": {}, "purpose": "dispute_evidence" } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "Created file" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/files/{id}/view": { "get": { "description": "View a file", "x-path": [ "files", "view" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "File contents" } } }, "description": "File contents" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "File does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices": { "post": { "description": "Create an invoice", "x-path": [ "invoices", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/InvoiceExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "description": "The customer who this invoice is for.", "type": "string" }, "billing_address": { "description": "The billing address for this invoice.", "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The city of the address." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The state or province of the address." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The postal or ZIP code of the address." }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ], "description": "The country of the address." } }, "additionalProperties": false }, { "type": "null" } ] }, "shipping_details": { "description": "Shipping details for this invoice.", "anyOf": [ { "type": "object", "properties": { "name": { "description": "Recipient's name for shipping.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "Recipient's phone number for shipping.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The shipping address for this invoice.", "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The city of the address." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The state or province of the address." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The postal or ZIP code of the address." }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ], "description": "The country of the address." } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "line_items": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "catalog" ], "description": "Discriminates this as a catalog-priced line item." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of this item." }, "discounts": { "description": "The discounts to apply to this line item.", "type": "array", "items": { "type": "string" } }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the invoice's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "price": { "description": "The ID of the catalog price for this line item.", "type": "string" }, "description": { "description": "Optional descriptive text for this line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "quantity", "price" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "Discriminates this as a one-off (custom) line item." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of this item." }, "discounts": { "description": "The discounts to apply to this line item.", "type": "array", "items": { "type": "string" } }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the invoice's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "name": { "type": "string", "minLength": 1, "description": "The display name for a one-off line item." }, "description": { "description": "Optional descriptive text for this line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit_amount": { "type": "integer", "minimum": 0, "description": "The unit amount in cents for a one-off line item." } }, "required": [ "type", "quantity", "name", "unit_amount" ], "additionalProperties": false } ] }, "description": "The line items for this invoice." }, "due_date": { "description": "The due date for this invoice as a Unix timestamp in milliseconds.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "days_until_due": { "description": "The number of days until the invoice is due. When the invoice is finalized, this will be used to calculate the due_date if set.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] }, "attachments": { "description": "The IDs of files to attach to this invoice.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "memo": { "description": "Internal memo for the invoice.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer": { "description": "Footer text displayed on the invoice.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_fields": { "description": "Custom fields for the invoice.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "default_taxes": { "description": "Default taxes to apply to all line items that don't specify their own taxes.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } } }, "required": [ "customer", "line_items" ], "additionalProperties": false, "example": { "customer": "cus_abc123", "line_items": [ { "type": "catalog", "price": "price_abc123", "quantity": 2 }, { "type": "custom", "name": "Custom service", "unit_amount": 1500, "quantity": 1 } ], "due_date": 1750086400000 } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Created invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List invoices", "x-path": [ "invoices", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/InvoiceExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/InvoiceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "invoice", "live": false, "id": "inv_2bA3FSNtE8Qmpg2ufwPmC2", "created_at": 1750000000000, "updated_at": 1750000000000, "billing_address": null, "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "due_date": 1750086400000, "days_until_due": null, "payments": [], "line_items": [], "metadata": {}, "number": "INV-001", "shipping_details": { "name": "John Doe", "phone": "+1 (555) 123-4567", "address": { "line1": "123 Hope St", "line2": null, "city": "Los Angeles", "state": "CA", "postal_code": "94111", "country": "US" } }, "status": "open", "default_taxes": [], "subtotal": 2000, "total_taxes": 0, "total": 2000, "amount_due": 2000, "amount_paid": 0, "external_sync": null, "attachments": [], "credit_notes": null, "memo": null, "footer": null, "custom_fields": null, "payment_link": null }, "has_more": false } } } }, "description": "List of invoices" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}": { "delete": { "description": "Delete an invoice", "x-path": [ "invoices", "delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "invoice" }, "id": { "type": "string" }, "deleted": { "default": true, "type": "boolean", "const": true } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false, "example": { "object": "invoice", "id": "inv_2bA3FSNtE8Qmpg2ufwPmC2", "deleted": true } } } }, "description": "Invoice deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be deleted in its current status" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "Get an invoice", "x-path": [ "invoices", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/InvoiceExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Retrieved invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update an invoice", "x-path": [ "invoices", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/InvoiceExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "description": "The ID of the customer for this invoice.", "type": "string" }, "billing_address": { "description": "The billing address for this invoice.", "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "shipping_details": { "description": "Shipping details for this invoice.", "anyOf": [ { "type": "object", "properties": { "name": { "description": "Recipient's name for shipping.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "Recipient's phone number for shipping.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The shipping address for this invoice.", "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "line_items": { "description": "The line items for this invoice. Replaces all existing line items.", "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "catalog" ], "description": "Discriminates this as a catalog-priced line item." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of this item." }, "discounts": { "description": "The discounts to apply to this line item.", "type": "array", "items": { "type": "string" } }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the invoice's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "price": { "description": "The ID of the catalog price for this line item.", "type": "string" }, "description": { "description": "Optional descriptive text for this line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "quantity", "price" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "Discriminates this as a one-off (custom) line item." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 9999, "multipleOf": 0.0001, "description": "The quantity of this item." }, "discounts": { "description": "The discounts to apply to this line item.", "type": "array", "items": { "type": "string" } }, "taxes": { "description": "The taxes to apply to this line item. If not provided, the invoice's default_taxes will be used.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } }, "name": { "type": "string", "minLength": 1, "description": "The display name for a one-off line item." }, "description": { "description": "Optional descriptive text for this line item.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit_amount": { "type": "integer", "minimum": 0, "description": "The unit amount in cents for a one-off line item." } }, "required": [ "type", "quantity", "name", "unit_amount" ], "additionalProperties": false } ] } }, "due_date": { "description": "The due date for this invoice as a Unix timestamp in milliseconds.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "days_until_due": { "description": "The number of days until the invoice is due. When the invoice is finalized, this will be used to calculate the due_date if set.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] }, "attachments": { "description": "The IDs of files to attach to this invoice. Replaces all existing attachments.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "memo": { "description": "Internal memo for the invoice.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer": { "description": "Footer text displayed on the invoice.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_fields": { "description": "Custom fields for the invoice.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "default_taxes": { "description": "Default taxes to apply to all line items that don't specify their own taxes. Only updateable on draft invoices.", "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "percentage", "display_name" ], "additionalProperties": false } } }, "additionalProperties": false, "example": { "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "due_date": 1750172800000 } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Updated invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/finalize": { "post": { "description": "Finalize an invoice", "x-path": [ "invoices", "finalize" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Finalized invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be finalized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/mark_paid": { "post": { "description": "Mark an invoice as paid", "x-path": [ "invoices", "mark_paid" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Invoice marked as paid" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be marked as paid" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/mark_uncollectible": { "post": { "description": "Mark an invoice as uncollectible", "x-path": [ "invoices", "mark_uncollectible" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Invoice marked as uncollectible" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be marked as uncollectible" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/pdf": { "get": { "description": "Generate a PDF rendering of an invoice", "x-path": [ "invoices", "pdf" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "string", "const": "preview" } ] } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "File contents" } } }, "description": "Generated PDF" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/receipt": { "get": { "description": "Generate a PDF rendering of an invoice receipt", "x-path": [ "invoices", "receipt" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "File contents" } } }, "description": "Generated PDF" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/send": { "post": { "description": "Send an invoice email notification", "x-path": [ "invoices", "send" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "email": { "description": "Email address to send the invoice notification to. Overrides the invoice customer's email. Falls back to the customer's email when omitted.", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Sent invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be sent" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/invoices/{id}/void": { "post": { "description": "Void an invoice", "x-path": [ "invoices", "void" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Voided invoice" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invoice cannot be voided in its current status" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payment_methods/{id}": { "get": { "description": "Get a payment method", "x-path": [ "payment_methods", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] } }, "additionalProperties": false } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } }, "description": "Retrieved payment method" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "PaymentMethod does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a payment method", "x-path": [ "payment_methods", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] } }, "additionalProperties": false } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_details": { "description": "Billing information for the payment method", "type": "object", "properties": { "address": { "description": "The cardholder’s billing address", "type": "object", "properties": { "city": { "description": "The address city.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "description": "The address country.", "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] }, "line1": { "description": "The first line of the address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "description": "The second line of the address (e.g. unit or floor number).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "description": "The address postal code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "description": "The address state.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "name": { "description": "The cardholder’s name", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "customer": { "description": "The customer to associate with the payment method", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } }, "description": "Updated payment method" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Resource does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payment_methods": { "get": { "description": "List all payment methods", "x-path": [ "payment_methods", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "type": "object", "properties": { "customer": { "anyOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/CustomerExpand" } ] } }, "additionalProperties": false } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/PaymentMethodFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PaymentMethodFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "payment_method", "id": "pm_VQ9SaYquIZTG2l0uRsmUr4", "live": false, "created_at": 1750000000000, "active": true, "billing_details": { "address": { "city": "Los Angeles", "country": "US", "line1": "123 Main Street", "line2": null, "postal_code": "90001", "state": "CA" }, "name": "John Doe" }, "card": { "object": "card", "live": false, "id": "card_inJ1dWsOEGezQOWd69qUW5", "created_at": 1750000000000, "bin": "42424242", "brand": "visa", "checks": { "address_line_1": "pass", "address_postal_code": "pass", "cvc": "pass" }, "country": "US", "exp_month": 1, "exp_year": 2030, "funding": "credit", "issuer": "Wells Fargo", "last4": "4242" }, "us_bank_account": null, "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "type": "card" }, "has_more": false } } } }, "description": "List of payment methods" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payment_methods/{id}/deactivate": { "post": { "description": "Deactivate a payment method", "x-path": [ "payment_methods", "deactivate" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } }, "description": "Deactivated payment method" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Payment method does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payments": { "post": { "description": "Create a payment", "x-path": [ "payments", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "The amount to charge, in USD cents. Required unless an `invoice` or checkout session is provided, in which case the amount defaults to the invoice total or remaining session amount.", "type": "integer", "minimum": 0 }, "capture_method": { "description": "When to capture the payment.", "default": "automatic", "type": "string", "enum": [ "automatic", "manual" ], "x-enum-descriptions": { "automatic": "Capture the payment immediately.", "manual": "Leave the payment requires_capture. You may [capture](/payments#capture) the payment later to collect funds." } }, "customer": { "description": "The customer to associate with the payment.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "description": "A description of the payment’s purpose.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoice": { "description": "The invoice to associate with the payment.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "description": "A [key-value store](/api-reference/metadata) that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use.", "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] }, "payment_method": { "anyOf": [ { "type": "string" }, { "anyOf": [ { "type": "object", "properties": { "billing_details": { "description": "The payment method holder’s billing details.", "type": "object", "properties": { "name": { "description": "The payment method holder’s name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The payment method holder’s billing address.", "type": "object", "properties": { "city": { "description": "The address city.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "description": "The address country.", "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] }, "line1": { "description": "The first line of the address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "description": "The second line of the address (e.g. unit or floor number).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "description": "The address postal code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "description": "The address state.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "card": { "type": "object", "properties": { "number": { "type": "string", "minLength": 1 }, "exp_month": { "type": "number", "minimum": 1, "maximum": 12 }, "exp_year": { "type": "number", "minimum": 2000 }, "cvc": { "type": "string", "minLength": 3, "maxLength": 4 } }, "required": [ "number", "exp_month", "exp_year", "cvc" ], "additionalProperties": false, "description": "The payment method’s card details." }, "setup_future_usage": { "description": "Set to `off_session` or `on_session` to activate the payment method for future use.", "x-enum-descriptions": { "off_session": "Save for future use with the intention of creating payments without customer interaction.", "on_session": "Save for future use with the intention of creating payments with customer interaction." }, "anyOf": [ { "type": "string", "enum": [ "off_session", "on_session" ] }, { "type": "null" } ] } }, "required": [ "card" ], "additionalProperties": false, "examples": [ { "billing_details": { "name": "John Doe", "address": { "postal_code": "94111" } }, "card": { "number": "4242424242424242", "exp_month": 1, "exp_year": 2030, "cvc": "123" } } ] }, { "type": "object", "properties": { "billing_details": { "description": "The payment method holder’s billing details.", "type": "object", "properties": { "name": { "description": "The payment method holder’s name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The payment method holder’s billing address.", "type": "object", "properties": { "city": { "description": "The address city.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "description": "The address country.", "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] }, "line1": { "description": "The first line of the address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "description": "The second line of the address (e.g. unit or floor number).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "description": "The address postal code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "description": "The address state.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "card": { "type": "object", "properties": { "encrypted_number": { "type": "string", "minLength": 1 }, "encrypted_expiry": { "type": "string", "minLength": 1 }, "encrypted_cvc": { "type": "string", "minLength": 1 } }, "required": [ "encrypted_number", "encrypted_expiry", "encrypted_cvc" ], "additionalProperties": false, "description": "RSA-OAEP encrypted card details. Each field is independently encrypted with the session public key and base64-encoded." }, "setup_future_usage": { "description": "Set to `off_session` or `on_session` to activate the payment method for future use.", "x-enum-descriptions": { "off_session": "Save for future use with the intention of creating payments without customer interaction.", "on_session": "Save for future use with the intention of creating payments with customer interaction." }, "anyOf": [ { "type": "string", "enum": [ "off_session", "on_session" ] }, { "type": "null" } ] } }, "required": [ "card" ], "additionalProperties": false, "examples": [ { "card": { "encrypted_number": "", "encrypted_expiry": "", "encrypted_cvc": "" } } ] }, { "type": "object", "properties": { "billing_details": { "description": "The payment method holder’s billing details.", "type": "object", "properties": { "name": { "description": "The payment method holder’s name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The payment method holder’s billing address.", "type": "object", "properties": { "city": { "description": "The address city.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "description": "The address country.", "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] }, "line1": { "description": "The first line of the address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "description": "The second line of the address (e.g. unit or floor number).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "description": "The address postal code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "description": "The address state.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "us_bank_account": { "type": "object", "properties": { "account_number": { "type": "string", "pattern": "^\\d{4,17}$" }, "routing_number": { "type": "string", "pattern": "^\\d{9}$" }, "account_type": { "type": "string", "enum": [ "checking", "savings" ] } }, "required": [ "account_number", "routing_number", "account_type" ], "additionalProperties": false, "description": "The payment method’s US bank account details." }, "setup_future_usage": { "description": "Set to `off_session` or `on_session` to activate the payment method for future use.", "x-enum-descriptions": { "off_session": "Save for future use with the intention of creating payments without customer interaction.", "on_session": "Save for future use with the intention of creating payments with customer interaction." }, "anyOf": [ { "type": "string", "enum": [ "off_session", "on_session" ] }, { "type": "null" } ] } }, "required": [ "us_bank_account" ], "additionalProperties": false, "examples": [ { "billing_details": { "name": "Jane Doe", "address": { "postal_code": "94111" } }, "us_bank_account": { "account_number": "000123456789", "routing_number": "110000000", "account_type": "checking" } } ] }, { "type": "object", "properties": { "billing_details": { "description": "The payment method holder’s billing details.", "type": "object", "properties": { "name": { "description": "The payment method holder’s name.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "description": "The payment method holder’s billing address.", "type": "object", "properties": { "city": { "description": "The address city.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "description": "The address country.", "anyOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ] }, "line1": { "description": "The first line of the address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "description": "The second line of the address (e.g. unit or floor number).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "description": "The address postal code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "description": "The address state.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "us_bank_account": { "type": "object", "properties": { "encrypted_account_number": { "type": "string", "minLength": 1 }, "encrypted_routing_number": { "type": "string", "minLength": 1 }, "account_type": { "type": "string", "enum": [ "checking", "savings" ] } }, "required": [ "encrypted_account_number", "encrypted_routing_number", "account_type" ], "additionalProperties": false, "description": "RSA-OAEP encrypted bank account details. Sensitive fields are independently encrypted with the session public key and base64-encoded." }, "setup_future_usage": { "description": "Set to `off_session` or `on_session` to activate the payment method for future use.", "x-enum-descriptions": { "off_session": "Save for future use with the intention of creating payments without customer interaction.", "on_session": "Save for future use with the intention of creating payments with customer interaction." }, "anyOf": [ { "type": "string", "enum": [ "off_session", "on_session" ] }, { "type": "null" } ] } }, "required": [ "us_bank_account" ], "additionalProperties": false, "examples": [ { "us_bank_account": { "encrypted_account_number": "", "encrypted_routing_number": "", "account_type": "checking" } } ] } ], "example": { "billing_details": { "name": "John Doe", "address": { "postal_code": "94111" } }, "card": { "number": "4242424242424242", "exp_month": 1, "exp_year": 2030, "cvc": "123" } }, "examples": [ { "billing_details": { "name": "John Doe", "address": { "postal_code": "94111" } }, "card": { "number": "4242424242424242", "exp_month": 1, "exp_year": 2030, "cvc": "123" } }, { "billing_details": { "name": "Jane Doe", "address": { "postal_code": "94111" } }, "us_bank_account": { "account_number": "000123456789", "routing_number": "110000000", "account_type": "checking" } } ] } ], "description": "The payment method to charge. Can be the ID of an existing payment method or an object containing payment method details." }, "statement_descriptor": { "description": "A statement descriptor for the payment. **This property overrides the default descriptor**. It must begin with your business name or storefront domain. Include only latin characters, exlcuding `<`, `>`, `\\`, `'`, `\"`, `*`.", "anyOf": [ { "type": "string", "minLength": 5, "maxLength": 12 }, { "type": "null" } ] } }, "required": [ "payment_method" ], "additionalProperties": false, "example": { "amount": 1000, "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1", "description": "Snowboard bindings", "payment_method": { "billing_details": { "name": "John Doe", "address": { "postal_code": "94111" } }, "card": { "number": "4242424242424242", "exp_month": 1, "exp_year": 2030, "cvc": "123" } } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Created payment" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/PaymentError" } ] } } }, "description": "Invalid request or payment error" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List all payments", "x-path": [ "payments", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/PaymentExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/PaymentFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PaymentFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "payment", "live": false, "id": "pay_lUY2g0TuPzN9qi4couahd3", "created_at": 1750000000000, "amount": 1000, "amount_capturable": 1000, "amount_received": 0, "amount_refunded": 0, "capture_method": "automatic", "customer": "customer", "description": "Payment for order 123", "dispute": null, "invoice": null, "metadata": {}, "payment_error": null, "payment_method": "payment_method", "session": "checkout_session", "statement_descriptor": null, "status": "succeeded" }, "has_more": false } } } }, "description": "List of payments" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payments/{id}": { "get": { "description": "Get a payment", "x-path": [ "payments", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/PaymentExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Retrieved payment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Payment does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a payment", "x-path": [ "payments", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Updated payment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Payment does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" } ] } } }, "description": "Conflicting request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payments/{id}/capture": { "post": { "description": "Capture a payment", "x-path": [ "payments", "capture" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Captured payment" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/PaymentError" } ] } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Payment does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/payments/{id}/cancel": { "post": { "description": "Cancel a payment", "x-path": [ "payments", "cancel" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Canceled payment" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/PaymentError" } ] } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Payment does not exist" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/prices": { "post": { "description": "Create a price", "x-path": [ "prices", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/PriceExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "description": "The product this price belongs to", "type": "string" }, "active": { "description": "Whether the price can be used for new purchases.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": { "description": "A short description of the price for internal use. Price descriptions are not shown to customers.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "amount": { "type": "integer", "minimum": 0, "description": "The price in cents" }, "type": { "default": "one_time", "description": "The price type.", "type": "string", "enum": [ "one_time" ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "required": [ "product", "amount" ], "additionalProperties": false, "example": { "product": "price_dz1NVvl5CSogERkeA9Ng67", "active": true, "description": "Standard price", "amount": 2999, "type": "one_time", "metadata": {} } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } }, "description": "Created price" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List all prices", "x-path": [ "prices", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/PriceExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/PriceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PriceFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PriceFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/PriceFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Price" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "price", "id": "price_dz1NVvl5CSogERkeA9Ng67", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "product": "prod_KDCnId9DMZSOA9MSaut4Q", "active": true, "description": "Standard price", "amount": 2999, "type": "one_time", "metadata": {} }, "has_more": false } } } }, "description": "List of prices" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/prices/{id}": { "get": { "description": "Get a price", "x-path": [ "prices", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/PriceExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } }, "description": "Price found" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Price not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a price", "x-path": [ "prices", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/PriceExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "description": "Whether the price can be used for new purchases.", "type": "boolean" }, "description": { "description": "A short description of the price for internal use. Price descriptions are not shown to customers.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "active": false, "name": "Intro rate", "metadata": {} } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } }, "description": "Updated price" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Price not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/products": { "post": { "description": "Create a product", "x-path": [ "products", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/ProductExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's name." }, "description": { "description": "An optional description of the product.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "active": { "description": "Whether the product can be used for new purchases.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "images": { "description": "Visual media representing the product.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false, "example": { "name": "Cosmos", "description": "Light roast coffee beans" } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "Created product" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "List all products", "x-path": [ "products", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/ProductExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/ProductFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ProductFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "product", "id": "prod_KDCnId9DMZSOA9MSaut4Q", "live": false, "created_at": 1750000000000, "updated_at": 1750000000000, "deleted": false, "name": "Cosmos", "description": "Light roast coffee beans", "active": true, "default_price": null, "prices": null, "images": [], "metadata": {} }, "has_more": false } } } }, "description": "List of products" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/products/{id}": { "delete": { "description": "Delete a product", "x-path": [ "products", "delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "product" }, "id": { "type": "string" }, "deleted": { "default": true, "type": "boolean", "const": true } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false, "example": { "object": "product", "id": "prod_KDCnId9DMZSOA9MSaut4Q", "deleted": true } } } }, "description": "Product deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Product not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "get": { "description": "Get a product", "x-path": [ "products", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/ProductExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "Product found" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Product not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "patch": { "description": "Update a product", "x-path": [ "products", "update" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/ProductExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The product's name.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional description of the product.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "active": { "description": "Whether the product can be used for new purchases.", "type": "boolean" }, "default_price": { "description": "The ID of the default price for this product.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "description": "Visual media representing the product.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/MetadataInput" }, { "type": "null" } ] } }, "additionalProperties": false, "example": { "name": "Summer 2026 Cotton Tee", "active": false } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "Updated product" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Product not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/InvalidRequestError" } ] } } }, "description": "Conflicting request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/refunds/{id}": { "get": { "description": "Get a refund", "x-path": [ "refunds", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/RefundExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "Retrieved refund" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Refund does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/refunds": { "get": { "description": "List all refunds", "x-path": [ "refunds", "list" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "description": "Optional object that allows you to [expand](/api-reference/expansion) certain ID fields to include related resources.", "$ref": "#/components/schemas/RefundExpand" } }, { "name": "ending_before", "in": "query", "schema": { "description": "A cursor for use in pagination. `ending_before` is an object ID that results will end before. Used to move backward through the list.", "type": "string" } }, { "name": "starting_after", "in": "query", "schema": { "description": "A cursor for use in pagination. `starting_after` is an object ID that results will start after. Used to move forward through the list.", "type": "string" } }, { "name": "limit", "in": "query", "schema": { "default": 50, "description": "Maximum number of objects to return.", "type": "number", "minimum": 1, "maximum": 1000 } }, { "name": "filters", "in": "query", "schema": { "description": "Filters to apply to the list. Combine multiple conditions with `and` and `or`.", "anyOf": [ { "$ref": "#/components/schemas/RefundFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RefundFilters" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "and": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RefundFilters" }, { "type": "object", "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/RefundFilters" } } }, "required": [ "or" ], "additionalProperties": false } ] } } }, "required": [ "and" ], "additionalProperties": false } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "description": "Literal representing the object’s type.", "type": "string", "const": "list" }, "has_more": { "type": "boolean", "description": "Whether there are more items in the list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" }, "description": "An array containing the current page of list items" } }, "required": [ "object", "has_more", "items" ], "additionalProperties": false, "example": { "object": "list", "items": { "object": "refund", "id": "re_3UgC74NSEMIWiFK5s3tZ82", "live": false, "created_at": 1750000000000, "amount": 1000, "failed_reason": null, "payment": "pay_lUY2g0TuPzN9qi4couahd3", "status": "succeeded" }, "has_more": false } } } }, "description": "List of refunds" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } }, "post": { "description": "Create a refund", "x-path": [ "refunds", "create" ], "parameters": [ { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/RefundExpand" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "description": "The payment to refund. Must have a status of `succeeded`.", "type": "string" }, "amount": { "description": "The amount to refund. Defaults to the full amount of the payment if omitted. Must be less than or equal to the payment’s `amount_refunded` subtracted from the payment’s `amount_received`.", "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "payment" ], "additionalProperties": false } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "Created refund" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/PaymentError" } ] } } }, "description": "Invalid request" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidRequestError" }, { "$ref": "#/components/schemas/IdempotencyError" } ] } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/requests/{id}": { "get": { "description": "Get a request", "x-path": [ "requests", "get" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "$ref": "#/components/schemas/RequestExpand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } }, "description": "Retrieved request" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Request does not exist" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } }, "/v1/stats": { "post": { "description": "Query arbitrary statistics", "x-path": [ "stats" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/StatisticQuery" } } }, "required": [ "stats" ], "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } }, "description": "Statistics results" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestError" } } }, "description": "Invalid request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "Too many requests error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Internal server error" } } } } } }