{ "components": { "headers": { "Idempotent-Replayed": { "description": "`true` when this is the stored answer to an earlier request with the same `Idempotency-Key`, rather than the result of running the request again. Absent otherwise.", "required": false, "schema": { "enum": [ "true" ], "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying. Sent on a 429 and on a 503.", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Limit": { "description": "The sustained per-minute rate of the rate-limit bucket that served this request. Sent while rate limiting is on.", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in that bucket right now. Sent while rate limiting is on.", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds at which that bucket is full again. Sent while rate limiting is on.", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Identifies this request. Quote it when contacting support.", "required": true, "schema": { "type": "string" } } }, "schemas": { "ApiKeyCreateRequest": { "additionalProperties": false, "properties": { "label": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A name for the key, shown in the console and on this object.", "title": "Label" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "The scopes the new key carries, such as customers:read, or * for every scope. Omit to give it the calling key's scopes. Each must be a known scope the calling key holds.", "title": "Scopes" } }, "title": "ApiKeyCreateRequest", "type": "object" }, "ApiKeyResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "id": { "description": "Unique identifier for the API key, beginning ak_.", "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name given to the key, or null if it has none.", "title": "Label" }, "last_used_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the key last authenticated a request, in Unix seconds, updated at most once a minute. Null if it has never been used.", "title": "Last Used At" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "api_key", "default": "api_key", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "prefix": { "description": "The first 16 characters of the key, such as bk_live_ and the start of its secret, to tell keys apart.", "title": "Prefix", "type": "string" }, "revoked_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the key was revoked, in Unix seconds, or null if it is active.", "title": "Revoked At" }, "scopes": { "description": "The scopes the key carries. * grants every scope.", "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full key. Present only in the response that creates it; null everywhere else.", "title": "Secret" } }, "required": [ "id", "object", "created", "livemode", "prefix", "label", "scopes", "last_used_at", "revoked_at", "secret" ], "title": "ApiKeyResponse", "type": "object" }, "AuditLogResponse": { "properties": { "action": { "description": "What was done, such as customer.created.", "title": "Action", "type": "string", "x-extensible-enum": [ "tenant.created", "api_key.created", "api_key.used", "api_key.revoked", "api_key.auth_failed", "api_key.insufficient_scope", "webhook_endpoint.created", "webhook_endpoint.updated", "webhook_endpoint.secret_rotated", "webhook_endpoint.deleted", "customer.created", "customer.updated", "customer.deleted", "customer.purged", "subscription.canceled", "subscription.paused", "subscription.resumed", "subscription.reactivated", "subscription.plan_change_started", "subscription.reauthorize_started", "import.mandate_started", "subscription.payment_method_updated", "subscription.trial_started", "subscription.trial_ended", "subscription.coupon_applied", "billing_portal.session_created", "billing_portal.session_revoked", "tenant.portal_branding_updated", "tenant.billing_address_updated", "tenant.billing_country_updated", "tenant.billing_vat_id_updated", "tenant.provider_credential_rotated", "tenant.mollie_connected", "tenant.mollie_profile_changed", "tenant.data_exported", "tenant.domain_set", "tenant.domain_checked", "tenant.domain_removed", "tenant.test_mode_email_enabled", "tenant.test_mode_email_disabled", "tenant.invoice_pdf_attach_enabled", "tenant.invoice_pdf_attach_disabled", "tenant.payment_methods_updated", "tenant.domain_email_enabled", "tenant.domain_email_disabled", "tenant.domain_portal_enabled", "tenant.domain_portal_disabled", "tenant.domain_portal_status_changed", "team.invite_sent", "team.invite_revoked", "team.member_disabled", "team.member_enabled", "operator.stepped_up", "meta_subscription.plan_changed", "refund.created", "dispute.created", "dispute.closed", "one_shot_payment.created", "one_shot_payment.confirmed", "dunning.notified", "meta_dunning.notified", "product.created", "product.updated", "product.archived", "price.created", "price.archived", "price.updated", "coupon.created", "coupon.updated", "coupon.redeemed", "tax_rate.created", "tax_rate.updated", "customer.country_derived", "customer.vat_validated", "customer.vat_verification_failed", "customer.vat_verification_unavailable", "invoice.created", "invoice.paid", "invoice.voided", "invoice.emailed", "rate_limit.exceeded" ] }, "actor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the actor, such as the API key's ak_ id or the operator's id. May be null when BillKit acted on its own.", "title": "Actor Id" }, "actor_type": { "description": "What performed the action, such as api_key, operator or portal_session, or system when BillKit acted on its own.", "title": "Actor Type", "type": "string", "x-extensible-enum": [ "api_key", "system", "reaper", "mollie_webhook", "portal_session", "operator", "checkout_session", "one_shot_payment" ] }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "id": { "description": "Unique identifier for the audit log entry, beginning al_.", "title": "Id", "type": "string" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client IP address of the request that performed the action, or null if there was no request.", "title": "Ip Address" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Details recorded with the action. Their keys depend on the action.", "title": "Metadata", "type": "object" }, "object": { "const": "audit_log", "default": "audit_log", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the object acted on, or null if the action has no single object.", "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Type of the object acted on, such as customer, or null if the action has no single object.", "title": "Resource Type" }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-Agent header of the request that performed the action, or null if there was none.", "title": "User Agent" } }, "required": [ "id", "object", "created", "livemode", "actor_type", "actor_id", "action", "resource_type", "resource_id", "metadata", "ip_address", "user_agent" ], "title": "AuditLogResponse", "type": "object" }, "BillingPortalSessionCreate": { "additionalProperties": false, "properties": { "deliver_email": { "default": false, "description": "Also email the portal link to the customer's address on file. When they have none, no email is sent and the session is still created.", "title": "Deliver Email", "type": "boolean" }, "return_url": { "description": "Where the portal sends the customer when they leave it.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Return Url", "type": "string" }, "subscription_id": { "description": "Id of the subscription the portal session covers.", "maxLength": 64, "minLength": 1, "title": "Subscription Id", "type": "string" } }, "required": [ "subscription_id", "return_url" ], "title": "BillingPortalSessionCreate", "type": "object" }, "BillingPortalSessionResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "customer_id": { "description": "Id of the customer the subscription belongs to.", "title": "Customer Id", "type": "string" }, "expires_at": { "description": "When the session expires regardless of use, in Unix seconds. It also expires earlier after a period without use.", "title": "Expires At", "type": "integer" }, "id": { "description": "Unique identifier for the portal session, prefixed bps_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "billing_portal.session", "default": "billing_portal.session", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "return_url": { "description": "Where the portal sends the customer when they leave it.", "title": "Return Url", "type": "string" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the subscription the session covers. Always set today; nullable for future session types.", "title": "Subscription Id" }, "token": { "description": "The session credential. Returned only in this response and never again; do not store it.", "title": "Token", "type": "string" }, "url": { "description": "The portal link to send the customer to. It carries the token, so treat it as a secret.", "title": "Url", "type": "string" } }, "required": [ "id", "object", "livemode", "subscription_id", "customer_id", "token", "url", "return_url", "created", "expires_at" ], "title": "BillingPortalSessionResponse", "type": "object" }, "BillingPortalSessionRevokeResponse": { "description": "A revoked billing portal session. The token is never returned again.", "properties": { "customer_id": { "description": "Id of the customer the subscription belongs to.", "title": "Customer Id", "type": "string" }, "id": { "description": "Unique identifier for the portal session, prefixed bps_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "billing_portal.session", "default": "billing_portal.session", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "revoked_at": { "description": "When the session was revoked, in Unix seconds.", "title": "Revoked At", "type": "integer" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the subscription the session covered. Always set today; nullable for future session types.", "title": "Subscription Id" } }, "required": [ "id", "object", "livemode", "subscription_id", "customer_id", "revoked_at" ], "title": "BillingPortalSessionRevokeResponse", "type": "object" }, "CheckoutSessionCompletedEvent": { "description": "The body of a `checkout.session.completed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CheckoutSessionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "checkout.session.completed", "description": "What happened. Always `checkout.session.completed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CheckoutSessionCompletedEvent", "type": "object" }, "CheckoutSessionCreate": { "additionalProperties": false, "properties": { "cancel_url": { "description": "Where the buyer is sent if they leave the payment without completing it.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Cancel Url", "type": "string" }, "country": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "description": "The buyer's ISO 3166-1 alpha-2 country, if known. Stored on the customer only when they have no country yet, so VAT applies to the first charge. Never overwrites an existing country.", "title": "Country" }, "coupon_code": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Code of a coupon to apply. Must be active and eligible for this price. A redemption is counted only when the first payment settles.", "title": "Coupon Code" }, "customer_email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "description": "Email for a new customer, created with the session. A new customer is always created; BillKit never matches an existing one by email. Exactly one of customer_id and customer_email.", "title": "Customer Email" }, "customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of an existing customer to check out. Exactly one of customer_id and customer_email.", "title": "Customer Id" }, "customer_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Name for the customer created from customer_email. Refused alongside customer_id.", "title": "Customer Name" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Key-value pairs stored on the session and echoed on it and on the checkout.session.completed event. BillKit does not interpret them.", "title": "Metadata" }, "payment_method": { "anyOf": [ { "enum": [ "creditcard", "directdebit", "ideal", "eps", "applepay", "paypal" ], "type": "string" }, { "type": "null" } ], "description": "The one payment method to offer. Must be in the price's payment_methods, and must be able to start a mandate, so directdebit is refused. When omitted, the methods the price allows and the account can accept are offered. Must be omitted when ui_mode is embedded.", "title": "Payment Method" }, "price_id": { "description": "Id of the recurring price the subscription is created on.", "title": "Price Id", "type": "string" }, "success_url": { "description": "Where the buyer is sent after completing the payment.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Success Url", "type": "string" }, "trial_days_override": { "anyOf": [ { "maximum": 180.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Trial length in days for this checkout, replacing the price's trial_days. 0 removes the price's trial. At most twice the price's trial_days, or 28 when that is under 14. Refused for a metered price.", "title": "Trial Days Override" }, "ui_mode": { "default": "hosted", "description": "hosted creates the payment now and returns a url to redirect the buyer to. embedded returns a client_secret for the embedded checkout element, where the buyer picks the payment method.", "enum": [ "hosted", "embedded" ], "title": "Ui Mode", "type": "string" } }, "required": [ "price_id", "success_url", "cancel_url" ], "title": "CheckoutSessionCreate", "type": "object" }, "CheckoutSessionExpiredEvent": { "description": "The body of a `checkout.session.expired` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CheckoutSessionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "checkout.session.expired", "description": "What happened. Always `checkout.session.expired` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CheckoutSessionExpiredEvent", "type": "object" }, "CheckoutSessionResponse": { "properties": { "cancel_url": { "description": "Where the buyer is sent if they leave without completing.", "title": "Cancel Url", "type": "string" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secret for mounting the embedded checkout element. Returned only in the response that creates an embedded session; null otherwise.", "title": "Client Secret" }, "coupon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the coupon applied from coupon_code. Null when none was applied.", "title": "Coupon Id" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "customer_country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The buyer's ISO 3166-1 alpha-2 country as known when the session completed. Null until then.", "title": "Customer Country Code" }, "customer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The buyer's email as known when the session completed. Null until then.", "title": "Customer Email" }, "customer_id": { "description": "Id of the customer checking out, including one created from customer_email.", "title": "Customer Id", "type": "string" }, "expires_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When an open embedded session expires, in Unix seconds. Null for a hosted session.", "title": "Expires At" }, "id": { "description": "Unique identifier for the checkout session, prefixed cs_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "default": {}, "description": "Key-value pairs set at creation. Always an object, empty when none were set.", "title": "Metadata", "type": "object" }, "object": { "const": "checkout.session", "default": "checkout.session", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the first payment. Null until the session completes.", "title": "Payment Id" }, "payment_method": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, { "type": "null" } ], "description": "The payment method requested, or for an embedded session the one the buyer chose. Null when none has been chosen yet.", "title": "Payment Method" }, "price_id": { "description": "Id of the price the subscription is created on.", "title": "Price Id", "type": "string" }, "status": { "description": "open until the first payment settles, then complete. A hosted session is expired when its payment fails; an embedded session stays open for a retry and is expired after expires_at.", "title": "Status", "type": "string", "x-extensible-enum": [ "open", "complete", "expired" ] }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the subscription the session created. Null until the session completes.", "title": "Subscription Id" }, "success_url": { "description": "Where the buyer is sent after completing the payment.", "title": "Success Url", "type": "string" }, "trial_days_override": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The trial length requested for this checkout, in days. Null when the price's trial_days applies.", "title": "Trial Days Override" }, "ui_mode": { "description": "hosted or embedded, as requested at creation.", "title": "Ui Mode", "type": "string", "x-extensible-enum": [ "hosted", "embedded" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment page to redirect the buyer to. Null for an embedded session until the element confirms a payment that needs one.", "title": "Url" } }, "required": [ "id", "object", "created", "livemode", "customer_id", "price_id", "success_url", "cancel_url", "status", "ui_mode", "url", "client_secret", "customer_email", "customer_country_code", "subscription_id", "payment_id", "expires_at", "trial_days_override", "coupon_id", "payment_method", "metadata" ], "title": "CheckoutSessionResponse", "type": "object" }, "CouponCreate": { "additionalProperties": false, "properties": { "amount_off_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Fixed amount off, in minor units of currency. Exactly one of percent_off and amount_off_cents.", "title": "Amount Off Cents" }, "applies_to_price_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Ids of the prices the coupon can be used with. Null or empty for any price.", "title": "Applies To Price Ids" }, "code": { "description": "The code customers enter. Stored trimmed and uppercased, so matching ignores case; must be unique on your account.", "maxLength": 64, "minLength": 1, "title": "Code", "type": "string" }, "currency": { "anyOf": [ { "maxLength": 3, "minLength": 3, "type": "string" }, { "type": "null" } ], "description": "Three-letter ISO 4217 currency of amount_off_cents and min_amount_cents; the coupon then applies only to prices in it. Required with either when your account has more than one currency enabled, and otherwise defaults to your one currency.", "title": "Currency" }, "discount_type": { "anyOf": [ { "enum": [ "percent", "fixed_amount" ], "type": "string" }, { "type": "null" } ], "description": "Optional. Implied by whichever of percent_off and amount_off_cents is set; must agree when sent.", "title": "Discount Type" }, "duration": { "default": "once", "description": "How long the discount applies once redeemed. once discounts the first charge; repeating every charge within duration_in_months months of the first discounted charge; forever every charge.", "enum": [ "once", "forever", "repeating" ], "title": "Duration", "type": "string" }, "duration_in_months": { "anyOf": [ { "maximum": 120.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Number of months a repeating coupon applies. Required when duration is repeating.", "title": "Duration In Months" }, "max_redemptions": { "anyOf": [ { "maximum": 2147483647.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Maximum number of times the coupon can be redeemed. Null for no limit.", "title": "Max Redemptions" }, "min_amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Minimum charge, before the discount, in minor units of currency, for the coupon to apply. Requires currency to be known. Null for no minimum.", "title": "Min Amount Cents" }, "percent_off": { "anyOf": [ { "description": "Percent off, more than 0 and at most 100, with up to two decimal places.", "exclusiveMinimum": 0.0, "maximum": 100.0, "type": "number" }, { "type": "null" } ], "description": "Percent off, more than 0 and at most 100, with up to two decimal places (12.5). Exactly one of percent_off and amount_off_cents.", "title": "Percent Off" }, "redeem_by": { "anyOf": [ { "maximum": 253402300799.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Last time the coupon can be redeemed, in Unix seconds. Null for no deadline.", "title": "Redeem By" } }, "required": [ "code" ], "title": "CouponCreate", "type": "object" }, "CouponCreatedEvent": { "description": "The body of a `coupon.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CouponResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "coupon.created", "description": "What happened. Always `coupon.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CouponCreatedEvent", "type": "object" }, "CouponResponse": { "properties": { "active": { "description": "Whether the code can be redeemed. false once withdrawn.", "title": "Active", "type": "boolean" }, "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount off in minor units of currency, when discount_type is fixed_amount; else null.", "title": "Amount Off Cents" }, "applies_to_price_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Ids of the prices the coupon can be used with. Null or empty for any price.", "title": "Applies To Price Ids" }, "code": { "description": "The code customers enter, uppercased.", "title": "Code", "type": "string" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Three-letter ISO 4217 currency of amount_off_cents and min_amount_cents; the coupon applies only to prices in it. Null for a percent coupon with no minimum, which applies in any currency.", "title": "Currency" }, "discount_type": { "description": "Which of percent_off and amount_off_cents this coupon sets.", "title": "Discount Type", "type": "string", "x-extensible-enum": [ "percent", "fixed_amount" ] }, "duration": { "description": "How long the discount applies once redeemed. once discounts the first charge; repeating every charge within duration_in_months months of the first discounted charge; forever every charge.", "title": "Duration", "type": "string", "x-extensible-enum": [ "once", "forever", "repeating" ] }, "duration_in_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of months a repeating coupon applies. Null otherwise.", "title": "Duration In Months" }, "id": { "description": "Unique identifier for the coupon, prefixed coup_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "max_redemptions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of redemptions. Null for no limit.", "title": "Max Redemptions" }, "min_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Minimum charge, before the discount, in minor units of currency. Null for no minimum.", "title": "Min Amount Cents" }, "object": { "const": "coupon", "default": "coupon", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "percent_off": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Percent off, more than 0 and at most 100 with up to two decimal places, when discount_type is percent; else null.", "title": "Percent Off" }, "redeem_by": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Last time the coupon can be redeemed, in Unix seconds. Null for no deadline.", "title": "Redeem By" }, "redemptions_count": { "description": "Number of times the coupon has been redeemed.", "title": "Redemptions Count", "type": "integer" } }, "required": [ "id", "object", "created", "livemode", "code", "discount_type", "percent_off", "amount_off_cents", "duration", "duration_in_months", "max_redemptions", "redemptions_count", "redeem_by", "applies_to_price_ids", "min_amount_cents", "currency", "active" ], "title": "CouponResponse", "type": "object" }, "CouponUpdate": { "additionalProperties": false, "description": "The coupon fields to change. Omitted fields are left alone.\n\n``max_redemptions``, ``redeem_by``, ``applies_to_price_ids`` and\n``min_amount_cents`` are cleared with ``null``, which lifts that\nrestriction. ``active`` cannot be cleared and refuses ``null`` with a 400.", "properties": { "active": { "description": "false withdraws the code so it can no longer be redeemed; true makes it available again.", "title": "Active", "type": "boolean" }, "applies_to_price_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Ids of the prices the coupon can be used with. null or empty allows any price.", "title": "Applies To Price Ids" }, "max_redemptions": { "anyOf": [ { "maximum": 2147483647.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Maximum number of times the coupon can be redeemed. null removes the limit.", "title": "Max Redemptions" }, "min_amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Minimum charge, before the discount, in minor units of currency. Refused on a coupon with no currency. null removes the minimum.", "title": "Min Amount Cents" }, "redeem_by": { "anyOf": [ { "maximum": 253402300799.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Last time the coupon can be redeemed, in Unix seconds. null removes the deadline.", "title": "Redeem By" } }, "title": "CouponUpdate", "type": "object" }, "CouponUpdatedEvent": { "description": "The body of a `coupon.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CouponResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "coupon.updated", "description": "What happened. Always `coupon.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CouponUpdatedEvent", "type": "object" }, "CouponValidateRequest": { "additionalProperties": false, "properties": { "amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "The charge before the discount, in minor units of currency, to check a minimum and get discount_cents and final_charge_cents back.", "title": "Amount Cents" }, "code": { "description": "The code to check. Case-insensitive.", "maxLength": 64, "minLength": 1, "title": "Code", "type": "string" }, "currency": { "anyOf": [ { "maxLength": 3, "minLength": 3, "type": "string" }, { "type": "null" } ], "description": "Three-letter ISO 4217 currency of the charge, used when price_id is not sent.", "title": "Currency" }, "price_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the price the code would be used with, to check a price or currency restriction.", "title": "Price Id" } }, "required": [ "code" ], "title": "CouponValidateRequest", "type": "object" }, "CouponValidateResponse": { "properties": { "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount off in minor units of currency when discount_type is fixed_amount; else null.", "title": "Amount Off Cents" }, "code": { "description": "The code checked, trimmed and uppercased.", "title": "Code", "type": "string" }, "coupon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the matching coupon. Null when no coupon has this code.", "title": "Coupon Id" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The coupon's currency. Null for a percent coupon with no minimum, which applies in any currency.", "title": "Currency" }, "discount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "What the coupon takes off amount_cents. Null unless valid is true and amount_cents was sent.", "title": "Discount Cents" }, "discount_type": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "percent", "fixed_amount" ] }, { "type": "null" } ], "description": "percent or fixed_amount. Null when no coupon has this code.", "title": "Discount Type" }, "duration": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "once", "forever", "repeating" ] }, { "type": "null" } ], "description": "once, repeating or forever. Null when no coupon has this code.", "title": "Duration" }, "final_charge_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "amount_cents after the discount. Null unless valid is true and amount_cents was sent.", "title": "Final Charge Cents" }, "object": { "const": "coupon_validation", "default": "coupon_validation", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "percent_off": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Percent off when discount_type is percent; else null.", "title": "Percent Off" }, "reason": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "coupon_not_found", "coupon_inactive", "coupon_expired", "coupon_exhausted", "coupon_price_mismatch", "coupon_currency_mismatch", "coupon_below_minimum" ] }, { "type": "null" } ], "description": "Why the code cannot be used. Null when valid is true.", "title": "Reason" }, "valid": { "description": "Whether the code can be redeemed for the charge described.", "title": "Valid", "type": "boolean" } }, "required": [ "object", "valid", "coupon_id", "code", "discount_type", "percent_off", "amount_off_cents", "currency", "duration", "discount_cents", "final_charge_cents", "reason" ], "title": "CouponValidateResponse", "type": "object" }, "CreditNoteCreatedEvent": { "description": "The body of a `credit_note.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CreditNoteResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "credit_note.created", "description": "What happened. Always `credit_note.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CreditNoteCreatedEvent", "type": "object" }, "CreditNoteResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "customer_id": { "description": "The customer the credited invoice was issued to.", "title": "Customer Id", "type": "string" }, "id": { "description": "Unique identifier for the credit note.", "title": "Id", "type": "string" }, "invoice_id": { "description": "The invoice this credit note reverses.", "title": "Invoice Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "number": { "description": "The credit note number, CN-YYYY-NNNNNN: its own sequential, gapless series per account and mode, separate from invoice numbers.", "title": "Number", "type": "string" }, "object": { "const": "credit_note", "default": "credit_note", "description": "String representing the object's type. Always credit_note.", "title": "Object", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The reason given on the refund that issued this credit note, if any.", "title": "Reason" }, "refund_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The refund whose settlement issued this credit note.", "title": "Refund Id" }, "subtotal_cents": { "description": "Amount credited excluding tax, in minor units of currency. A positive magnitude.", "title": "Subtotal Cents", "type": "integer" }, "tax_cents": { "description": "VAT credited, in minor units of currency. A positive magnitude; 0 when the credited invoice carried no tax.", "title": "Tax Cents", "type": "integer" }, "tax_country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Two-letter ISO country code whose VAT treatment applied, as on the credited invoice. Null when none applied.", "title": "Tax Country Code" }, "tax_rate_basis_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "VAT rate credited, in basis points (2100 is 21%). Null when no rate applied.", "title": "Tax Rate Basis Points" }, "tax_reverse_charged": { "description": "True when the credited sale was reverse-charged, so no VAT is credited.", "title": "Tax Reverse Charged", "type": "boolean" }, "total_cents": { "description": "Amount credited including tax, in minor units of currency: subtotal_cents plus tax_cents.", "title": "Total Cents", "type": "integer" } }, "required": [ "id", "object", "created", "livemode", "invoice_id", "refund_id", "customer_id", "number", "currency", "subtotal_cents", "tax_cents", "total_cents", "tax_country_code", "tax_reverse_charged", "tax_rate_basis_points", "reason" ], "title": "CreditNoteResponse", "type": "object" }, "CustomerCreate": { "additionalProperties": false, "properties": { "country_code": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "description": "Two-letter ISO 3166-1 country code, stored uppercase. Selects the tax rate the customer is charged. When unset, BillKit fills it from the country seen at checkout or on a payment.", "title": "Country Code" }, "email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "description": "The customer's email address. Not unique: two customers can share one.", "title": "Email" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Key-value pairs stored on the customer and returned with it.", "title": "Metadata" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "The customer's full name or business name.", "title": "Name" }, "test_clock_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Test mode only: the test clock to attach the customer to. Refused on a live-mode key.", "title": "Test Clock Id" } }, "title": "CustomerCreate", "type": "object" }, "CustomerCreatedEvent": { "description": "The body of a `customer.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CustomerResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "customer.created", "description": "What happened. Always `customer.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CustomerCreatedEvent", "type": "object" }, "CustomerDeletedEvent": { "description": "The body of a `customer.deleted` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CustomerResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "customer.deleted", "description": "What happened. Always `customer.deleted` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CustomerDeletedEvent", "type": "object" }, "CustomerPurgeRequest": { "additionalProperties": false, "properties": { "confirmed": { "default": false, "description": "Must be true, confirming that the erasure is intended. It cannot be undone.", "title": "Confirmed", "type": "boolean" } }, "title": "CustomerPurgeRequest", "type": "object" }, "CustomerResponse": { "properties": { "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Two-letter ISO 3166-1 country code, uppercase, that selects the customer's tax rate. Null when neither declared nor seen at checkout or on a payment.", "title": "Country Code" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's email address, or null.", "title": "Email" }, "id": { "description": "Unique identifier for the customer, prefixed cus_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value pairs attached to the customer.", "title": "Metadata", "type": "object" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's full name or business name, or null.", "title": "Name" }, "object": { "const": "customer", "default": "customer", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "provisional": { "description": "True while the customer exists only because a checkout was started and not yet paid. Becomes false when a payment succeeds.", "title": "Provisional", "type": "boolean" }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/CustomerStatsInfo" }, { "type": "null" } ], "description": "Subscription count and lifetime payments. Null unless the request asked for expand=stats." }, "test_clock_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The test clock this customer is attached to, or null.", "title": "Test Clock Id" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's VAT registration number, set with POST /v1/customers/{customer_id}/vat_number, or null.", "title": "Vat Number" }, "vat_number_validated": { "description": "Whether VIES confirmed vat_number as valid. Charges reverse-charge VAT only when it is true and country_code differs from your account's country.", "title": "Vat Number Validated", "type": "boolean" } }, "required": [ "id", "object", "created", "livemode", "email", "name", "metadata", "country_code", "vat_number", "vat_number_validated", "test_clock_id", "provisional", "stats" ], "title": "CustomerResponse", "type": "object" }, "CustomerStatsInfo": { "description": "A customer's live subscription count and lifetime net payments.\n\n``subscription_count`` counts ``active`` and ``trialing`` subscriptions.\n``lifetime_cents`` is paid charges minus succeeded refunds, across\nsubscription and one-off payments. ``currency`` is null when there is\nnothing to report or the charges span more than one currency.", "properties": { "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of lifetime_cents, or null when there is nothing to report or the charges span more than one.", "title": "Currency" }, "lifetime_cents": { "description": "Paid charges minus succeeded refunds, in minor units of currency, across subscription and one-off payments.", "title": "Lifetime Cents", "type": "integer" }, "object": { "const": "customer.stats", "default": "customer.stats", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "subscription_count": { "description": "Number of the customer's active and trialing subscriptions.", "title": "Subscription Count", "type": "integer" } }, "required": [ "object", "subscription_count", "lifetime_cents", "currency" ], "title": "CustomerStatsInfo", "type": "object" }, "CustomerUpdate": { "additionalProperties": false, "description": "The customer fields to change. Omitted fields are left alone.\n\n``name`` is cleared with ``null``. ``email``, ``country_code`` and\n``metadata`` cannot be cleared and refuse ``null`` with a 400.\n``metadata`` replaces the stored object whole; send ``{}`` to empty it.", "properties": { "country_code": { "description": "Two-letter ISO 3166-1 country code, stored uppercase. Selects the tax rate the customer is charged.", "maxLength": 2, "minLength": 2, "title": "Country Code", "type": "string" }, "email": { "description": "The customer's email address.", "format": "email", "title": "Email", "type": "string" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Replaces the stored metadata whole. Send {} to empty it.", "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "title": "Metadata", "type": "object" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "The customer's full name or business name. null clears it.", "title": "Name" } }, "title": "CustomerUpdate", "type": "object" }, "CustomerUpdatedEvent": { "description": "The body of a `customer.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/CustomerResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "customer.updated", "description": "What happened. Always `customer.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "CustomerUpdatedEvent", "type": "object" }, "CustomerVatNumberRequest": { "additionalProperties": false, "description": "A VAT registration number to validate against VIES, or null to clear it.", "properties": { "country_code": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "description": "Two-letter ISO 3166-1 country code to set on the customer first, stored uppercase. VIES checks the number against the customer's country.", "title": "Country Code" }, "vat_number": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "The VAT registration number, with its two-letter country prefix (NL123456789B01). It is checked against VIES, and a number VIES rejects returns 400 and is not stored. null clears the number.", "title": "Vat Number" } }, "title": "CustomerVatNumberRequest", "type": "object" }, "DeletedResource": { "description": "Returned by a ``DELETE``: the object is gone and further requests for it return 404.", "properties": { "deleted": { "const": true, "default": true, "description": "Always true.", "title": "Deleted", "type": "boolean" }, "id": { "description": "Id of the deleted object.", "title": "Id", "type": "string" }, "object": { "description": "Type of the deleted object, such as customer.", "title": "Object", "type": "string" } }, "required": [ "id", "object", "deleted" ], "title": "DeletedResource", "type": "object" }, "DisputeClosedEvent": { "description": "The body of a `dispute.closed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/DisputeResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "dispute.closed", "description": "What happened. Always `dispute.closed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "DisputeClosedEvent", "type": "object" }, "DisputeCreatedEvent": { "description": "The body of a `dispute.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/DisputeResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "dispute.created", "description": "What happened. Always `dispute.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "DisputeCreatedEvent", "type": "object" }, "DisputeResponse": { "properties": { "amount_cents": { "description": "Amount the chargeback pulled back, in minor units of currency.", "title": "Amount Cents", "type": "integer" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "id": { "description": "Unique identifier for the dispute.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "dispute", "default": "dispute", "description": "String representing the object's type. Always dispute.", "title": "Object", "type": "string" }, "one_shot_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The one-off payment the chargeback was opened against. Null when it is against a subscription payment.", "title": "One Shot Payment Id" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription payment the chargeback was opened against. Null when it is against a one-off payment.", "title": "Payment Id" }, "provider_chargeback_id": { "description": "The payment provider's id for the chargeback.", "title": "Provider Chargeback Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The reason the provider reported for the chargeback, such as Fraudulent. Null when none was given.", "title": "Reason" }, "reversed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the chargeback was reversed at the provider, in Unix seconds. Null while the dispute is open.", "title": "Reversed At" }, "status": { "description": "open while the funds are withdrawn; won once the chargeback is reversed and the funds return. There is no lost state: a chargeback that stands stays open.", "title": "Status", "type": "string", "x-extensible-enum": [ "open", "won" ] }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription behind payment_id. Null for a one-off payment.", "title": "Subscription Id" } }, "required": [ "id", "object", "created", "livemode", "payment_id", "one_shot_payment_id", "subscription_id", "provider_chargeback_id", "amount_cents", "currency", "reason", "status", "reversed_at" ], "title": "DisputeResponse", "type": "object" }, "DunningEmailRequiredEvent": { "description": "The body of a `dunning.email_required` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/DunningNotification", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "dunning.email_required", "description": "What happened. Always `dunning.email_required` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "DunningEmailRequiredEvent", "type": "object" }, "DunningNotification": { "description": "``dunning.email_required``: a failed renewal the customer should hear about.", "properties": { "amount_cents": { "description": "Amount of the failed charge, in minor units of currency.", "title": "Amount Cents", "type": "integer" }, "attempt": { "description": "How many dunning notices this subscription has had, this one included.", "title": "Attempt", "type": "integer" }, "currency": { "description": "ISO 4217 code of the failed charge's currency.", "title": "Currency", "type": "string" }, "customer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's email address, or null if none is on file.", "title": "Customer Email" }, "customer_id": { "description": "Id of the subscription's customer.", "title": "Customer Id", "type": "string" }, "failed_at": { "description": "When the failed charge was made, in Unix seconds.", "title": "Failed At", "type": "integer" }, "failed_payment_id": { "description": "Id of the payment that failed.", "title": "Failed Payment Id", "type": "string" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider's decline reason for the failed charge, or null if it gave none.", "title": "Failure Reason" }, "next_payment_attempt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When BillKit will try the charge again, in Unix seconds. Null when no further automatic attempt is coming, so the customer must act.", "title": "Next Payment Attempt" }, "object": { "const": "dunning_notification", "default": "dunning_notification", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "payment_method": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, { "type": "null" } ], "description": "The payment method the failed charge used, or null if not known.", "title": "Payment Method" }, "subscription_id": { "description": "Id of the subscription whose renewal failed.", "title": "Subscription Id", "type": "string" } }, "required": [ "object", "subscription_id", "customer_id", "customer_email", "failure_reason", "failed_payment_id", "failed_at", "amount_cents", "currency", "payment_method", "attempt", "next_payment_attempt" ], "title": "DunningNotification", "type": "object" }, "Error": { "additionalProperties": true, "description": "Every error response, whatever its status, has this shape.", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "What went wrong." } }, "required": [ "error" ], "title": "Error", "type": "object" }, "ErrorDetail": { "additionalProperties": true, "properties": { "code": { "description": "What went wrong, stable across releases. Open: new values are added without notice, so branch on the ones you handle and fall back on `message` for the rest.", "type": "string", "x-extensible-enum": [ "authentication_required", "invalid_api_key", "revoked_api_key", "resource_missing", "parameter_invalid", "parameter_missing", "parameter_unknown", "route_not_found", "method_not_allowed", "state_conflict", "mode_mismatch", "idempotency_key_in_use", "idempotency_in_progress", "operation_pending", "rate_limited", "request_too_large", "service_unavailable", "insufficient_scope", "unhandled", "not_implemented", "rendering_pending", "configuration_missing", "invoice_not_voidable", "charge_already_refunded", "charge_disputed", "refund_duplicate", "payment_refused", "webhook_endpoint_disabled", "webhook_endpoint_limit_reached", "subscription_past_due", "tenant_suspended" ] }, "message": { "description": "A human-readable explanation. Wording may change; branch on `code`.", "type": "string" }, "param": { "description": "The request parameter the error is about, when there is one.", "type": "string" }, "reason": { "description": "A finer-grained cause, for the codes that have more than one. Open: new values are added without notice, so branch on the ones you handle and fall back on `message` for the rest.", "type": "string", "x-extensible-enum": [ "vat_not_recognised", "vat_id_locked", "no_active_mandate", "payment_refused", "period_window_expired", "plan_change_not_supported", "quote_expired", "renewal_processing", "customer_not_registered_with_provider", "activation_required", "not_attempted", "outcome_unknown", "coupon_invalid", "coupon_expired", "coupon_exhausted", "coupon_not_applicable", "coupon_already_applied", "idempotency_key_too_long", "idempotency_key_blank", "customer_has_active_subscription", "customer_has_open_invoice", "nul_character" ] }, "request_id": { "description": "The same id as the `X-Request-Id` response header.", "type": "string" }, "type": { "description": "The broad class of error. Open: new values are added without notice, so branch on the ones you handle and fall back on `message` for the rest.", "type": "string", "x-extensible-enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "conflict_error", "rate_limit_error", "payment_error", "api_error" ] } }, "required": [ "type", "code", "message" ], "title": "ErrorDetail", "type": "object" }, "EventResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedCustomer" }, { "type": "null" } ], "description": "The customer named by data.customer_id. Null unless the request asked for expand=customer, and null when the payload names no customer or it no longer exists." }, "data": { "additionalProperties": true, "description": "The object the event is about, as it stood when the event was recorded. Its shape depends on type.", "title": "Data", "type": "object" }, "id": { "description": "Unique identifier for the event, beginning evt_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "event", "default": "event", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update event, the previous values of the fields that changed, keyed as in data. Null when the event records no such change.", "title": "Previous Attributes" }, "type": { "description": "What happened, such as customer.created.", "title": "Type", "type": "string", "x-extensible-enum": [ "checkout.session.completed", "checkout.session.expired", "customer.created", "customer.updated", "customer.deleted", "subscription.created", "subscription.updated", "subscription.canceled", "subscription.past_due", "subscription.paused", "subscription.resumed", "subscription.reactivated", "subscription.plan_changed", "subscription.trial_started", "subscription.trial_will_end", "subscription.trial_ended", "subscription.payment_method_updated", "subscription.coupon_applied", "subscription.coupon_expired", "payment.succeeded", "payment.failed", "one_shot_payment.succeeded", "one_shot_payment.failed", "one_shot_payment.refunded", "refund.created", "refund.succeeded", "refund.failed", "dispute.created", "dispute.closed", "invoice.created", "invoice.upcoming", "invoice.paid", "invoice.payment_failed", "invoice.voided", "invoice.marked_uncollectible", "credit_note.created", "product.created", "product.updated", "product.archived", "price.created", "price.updated", "price.archived", "coupon.created", "coupon.updated", "webhook_endpoint.created", "webhook_endpoint.updated", "webhook_endpoint.deleted", "dunning.email_required" ] } }, "required": [ "id", "object", "created", "livemode", "type", "data", "previous_attributes", "customer" ], "title": "EventResponse", "type": "object" }, "EventTypeListResponse": { "description": "Every event type a webhook endpoint can subscribe to, and the wildcard for all of them.", "properties": { "data": { "description": "Every event type BillKit sends, such as customer.created.", "items": { "type": "string" }, "title": "Data", "type": "array" }, "object": { "const": "event_type_list", "default": "event_type_list", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "wildcard": { "description": "The value to put in enabled_events to receive every event type, including future ones.", "title": "Wildcard", "type": "string" } }, "required": [ "object", "data", "wildcard" ], "title": "EventTypeListResponse", "type": "object" }, "ExpandedCustomer": { "description": "A summary of a customer, added by ``expand=customer``.", "properties": { "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's two-letter ISO 3166-1 country code. Null if not known.", "title": "Country Code" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's email address. Null if none is set.", "title": "Email" }, "id": { "description": "Unique identifier for the customer, prefixed cus_.", "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's name. Null if none is set.", "title": "Name" }, "object": { "const": "customer.summary", "default": "customer.summary", "description": "String representing the object's type.", "title": "Object", "type": "string" } }, "required": [ "id", "object", "name", "email", "country_code" ], "title": "ExpandedCustomer", "type": "object" }, "ExpandedPrice": { "description": "A summary of a price and its product name, added by ``expand=price`` or ``expand=prices``.\n\nOn a metered price with a rate below one minor unit, ``amount_cents`` is\nrounded; ``unit_amount_decimal`` is the rate actually charged.\n``payment_methods`` is what the price allows; a given checkout may offer\nfewer, depending on your provider account and the buyer's country.", "properties": { "active": { "description": "Whether the price is on sale. An inactive price cannot be used for new checkouts.", "title": "Active", "type": "boolean" }, "amount_cents": { "description": "Amount per interval, or per unit on a metered price, in minor units of currency. Rounded on a metered price with a rate below one minor unit; 0 on a tiered price.", "title": "Amount Cents", "type": "integer" }, "billing_scheme": { "description": "per_unit charges amount_cents per unit; tiered prices by the price's tiers.", "title": "Billing Scheme", "type": "string", "x-extensible-enum": [ "per_unit", "tiered" ] }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "id": { "description": "Unique identifier for the price, prefixed price_.", "title": "Id", "type": "string" }, "interval": { "description": "Billing interval: month or year.", "title": "Interval", "type": "string", "x-extensible-enum": [ "month", "year" ] }, "object": { "const": "price.summary", "default": "price.summary", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "payment_methods": { "description": "Payment methods the price allows at checkout. A given checkout may offer fewer, depending on your provider account and the buyer's country.", "items": { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, "title": "Payment Methods", "type": "array" }, "payment_methods_from_account": { "description": "True when the price follows your account's payment methods, false when it has its own list.", "title": "Payment Methods From Account", "type": "boolean" }, "product_id": { "description": "Id of the product the price belongs to.", "title": "Product Id", "type": "string" }, "product_name": { "description": "Name of that product.", "title": "Product Name", "type": "string" }, "tax_behavior": { "description": "Whether amount_cents includes VAT (inclusive), excludes it (exclusive) or is unspecified.", "title": "Tax Behavior", "type": "string", "x-extensible-enum": [ "inclusive", "exclusive", "unspecified" ] }, "tiers_mode": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "graduated", "volume" ] }, { "type": "null" } ], "description": "graduated or volume on a tiered price. Null otherwise.", "title": "Tiers Mode" }, "trial_days": { "description": "Days of free trial before the first charge, 0 for none.", "title": "Trial Days", "type": "integer" }, "unit_amount_decimal": { "description": "The per-unit rate actually charged, in minor units of currency, as a decimal string.", "title": "Unit Amount Decimal", "type": "string" }, "usage_type": { "description": "licensed bills a fixed amount each period; metered bills the usage reported.", "title": "Usage Type", "type": "string", "x-extensible-enum": [ "licensed", "metered" ] } }, "required": [ "id", "object", "product_id", "product_name", "amount_cents", "unit_amount_decimal", "currency", "interval", "usage_type", "active", "trial_days", "payment_methods", "tax_behavior", "billing_scheme", "tiers_mode" ], "title": "ExpandedPrice", "type": "object" }, "ExpandedSubscription": { "description": "A summary of a subscription, added by ``expand=subscription``.", "properties": { "id": { "description": "Unique identifier for the subscription, prefixed sub_.", "title": "Id", "type": "string" }, "object": { "const": "subscription.summary", "default": "subscription.summary", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "price_id": { "description": "Id of the price the subscription is billed at.", "title": "Price Id", "type": "string" }, "status": { "description": "The subscription's status.", "title": "Status", "type": "string", "x-extensible-enum": [ "incomplete", "trialing", "active", "past_due", "canceled" ] } }, "required": [ "id", "object", "status", "price_id" ], "title": "ExpandedSubscription", "type": "object" }, "InvoiceCreatedEvent": { "description": "The body of a `invoice.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/InvoiceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.created", "description": "What happened. Always `invoice.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoiceCreatedEvent", "type": "object" }, "InvoiceEmailResponse": { "description": "Confirms an invoice email was queued, and the address it was sent to.\n\n``recipient`` is the address recorded on the invoice, which can differ\nfrom the customer's current email. Sending is best effort: this confirms\nthe email was queued, not that it was delivered.", "properties": { "invoice_id": { "description": "The invoice that was emailed.", "title": "Invoice Id", "type": "string" }, "object": { "const": "invoice.email", "default": "invoice.email", "description": "String representing the object's type. Always invoice.email.", "title": "Object", "type": "string" }, "recipient": { "description": "The address the email was sent to: the one recorded on the invoice, which can differ from the customer's current email.", "title": "Recipient", "type": "string" }, "sent": { "default": true, "description": "Always true: the email was queued. Delivery is best effort and not confirmed.", "title": "Sent", "type": "boolean" } }, "required": [ "object", "invoice_id", "recipient", "sent" ], "title": "InvoiceEmailResponse", "type": "object" }, "InvoiceLineItemResponse": { "properties": { "amount_cents": { "description": "The line's amount excluding tax, in minor units of currency. Negative on a credit line, such as unused time credited back from a previous plan.", "title": "Amount Cents", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "description": { "description": "What the line bills, as printed on the invoice: the plan or product name, or a credit's label.", "title": "Description", "type": "string" }, "id": { "description": "Unique identifier for the line item.", "title": "Id", "type": "string" }, "object": { "const": "invoice_line_item", "default": "invoice_line_item", "description": "String representing the object's type. Always invoice_line_item.", "title": "Object", "type": "string" }, "period_end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "End of the billing period this line covers, in Unix seconds. Null when the line buys no period, such as a one-off sale.", "title": "Period End" }, "period_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Start of the billing period this line covers, in Unix seconds. Null when the line buys no period, such as a one-off sale.", "title": "Period Start" }, "quantity": { "description": "Units billed on this line: 1 for a fixed charge, the period's total usage for a metered line.", "title": "Quantity", "type": "integer" }, "tax_rate_basis_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "VAT rate applied to the line, in basis points (2100 is 21%). Null when no rate was recorded.", "title": "Tax Rate Basis Points" } }, "required": [ "id", "object", "description", "amount_cents", "currency", "quantity", "tax_rate_basis_points", "period_start", "period_end" ], "title": "InvoiceLineItemResponse", "type": "object" }, "InvoiceMarkedUncollectibleEvent": { "description": "The body of a `invoice.marked_uncollectible` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/InvoiceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.marked_uncollectible", "description": "What happened. Always `invoice.marked_uncollectible` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoiceMarkedUncollectibleEvent", "type": "object" }, "InvoicePaidEvent": { "description": "The body of a `invoice.paid` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/InvoiceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.paid", "description": "What happened. Always `invoice.paid` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoicePaidEvent", "type": "object" }, "InvoicePaymentFailedEvent": { "description": "The body of a `invoice.payment_failed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/InvoiceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.payment_failed", "description": "What happened. Always `invoice.payment_failed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoicePaymentFailedEvent", "type": "object" }, "InvoiceResponse": { "properties": { "billing_address_at_invoice_time": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The billing address as invoiced. Today it carries only country_code; null when the customer had no country.", "title": "Billing Address At Invoice Time" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedCustomer" }, { "type": "null" } ], "description": "The customer as they are now, as a summary. Null unless the request asked for expand=customer. The *_at_invoice_time fields are what the document says." }, "customer_business_name_at_invoice_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's business name as invoiced. Null when none was on record at charge time.", "title": "Customer Business Name At Invoice Time" }, "customer_email_at_invoice_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's email as invoiced, copied from the charge. Not updated when the customer changes later.", "title": "Customer Email At Invoice Time" }, "customer_id": { "description": "The customer this invoice was issued to.", "title": "Customer Id", "type": "string" }, "customer_name_at_invoice_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's name as invoiced, copied from the charge. Not updated when the customer changes later.", "title": "Customer Name At Invoice Time" }, "customer_vat_number_at_invoice_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer's VAT number as invoiced, the one any reverse charge was decided against. Null when none was on record at charge time.", "title": "Customer Vat Number At Invoice Time" }, "discount_cents": { "description": "Amount a coupon took off the subtotal, excluding tax, in minor units of currency. 0 when no coupon applied.", "title": "Discount Cents", "type": "integer" }, "due_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When payment of an open metered invoice falls due, in Unix seconds. Null on an invoice issued already paid.", "title": "Due At" }, "id": { "description": "Unique identifier for the invoice.", "title": "Id", "type": "string" }, "lines": { "description": "The invoice's line items, in the order printed on the document.", "items": { "$ref": "#/components/schemas/InvoiceLineItemResponse" }, "title": "Lines", "type": "array" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "number": { "description": "The invoice number, YYYY-NNNNNN: sequential and gapless per account and mode.", "title": "Number", "type": "string" }, "object": { "const": "invoice", "default": "invoice", "description": "String representing the object's type. Always invoice.", "title": "Object", "type": "string" }, "one_shot_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The one-off payment this invoice documents. Set instead of payment_id for a one-off sale; null otherwise.", "title": "One Shot Payment Id" }, "paid_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the invoice was paid, in Unix seconds. Null until it is.", "title": "Paid At" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription payment this invoice documents. Null for a one-off sale, and on a metered invoice until its charge is paid.", "title": "Payment Id" }, "pdf_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Always null. Download the PDF from GET /v1/invoices/{invoice_id}/pdf.", "title": "Pdf Url" }, "status": { "description": "One of open (a metered period awaiting its charge), paid, uncollectible (collection was given up) or void.", "title": "Status", "type": "string", "x-extensible-enum": [ "open", "paid", "uncollectible", "void" ] }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription this invoice bills. Null for a one-off sale.", "title": "Subscription Id" }, "subtotal_cents": { "description": "Amount excluding tax and before any discount, in minor units of currency.", "title": "Subtotal Cents", "type": "integer" }, "tax_cents": { "description": "VAT charged, in minor units of currency. 0 when no tax applied or the charge was reverse-charged.", "title": "Tax Cents", "type": "integer" }, "tax_country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Two-letter ISO country code whose VAT treatment applied. Null when the customer had no country and no tax was computed.", "title": "Tax Country Code" }, "tax_reverse_charged": { "description": "True when the customer held a validated VAT number in another EU country, so no VAT was charged and the customer self-accounts for it.", "title": "Tax Reverse Charged", "type": "boolean" }, "total_cents": { "description": "Amount charged including tax, in minor units of currency: subtotal_cents minus discount_cents plus tax_cents.", "title": "Total Cents", "type": "integer" }, "voided_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the invoice was voided, in Unix seconds. Null unless status is void.", "title": "Voided At" } }, "required": [ "id", "object", "created", "livemode", "customer_id", "subscription_id", "payment_id", "one_shot_payment_id", "number", "currency", "subtotal_cents", "discount_cents", "tax_cents", "total_cents", "tax_country_code", "tax_reverse_charged", "status", "due_at", "paid_at", "voided_at", "pdf_url", "customer_email_at_invoice_time", "customer_name_at_invoice_time", "customer_business_name_at_invoice_time", "customer_vat_number_at_invoice_time", "billing_address_at_invoice_time", "lines", "customer" ], "title": "InvoiceResponse", "type": "object" }, "InvoiceUpcomingEvent": { "description": "The body of a `invoice.upcoming` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/UpcomingInvoice", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.upcoming", "description": "What happened. Always `invoice.upcoming` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoiceUpcomingEvent", "type": "object" }, "InvoiceVoid": { "additionalProperties": false, "description": "Optional parameters for voiding an invoice. The body may be omitted.", "properties": { "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Why the invoice is being voided. Recorded in the audit log only; it is not written to the invoice or its PDF.", "title": "Reason" } }, "title": "InvoiceVoid", "type": "object" }, "InvoiceVoidedEvent": { "description": "The body of a `invoice.voided` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/InvoiceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "invoice.voided", "description": "What happened. Always `invoice.voided` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "InvoiceVoidedEvent", "type": "object" }, "ListResponse_ApiKeyResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/ApiKeyResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[ApiKeyResponse]", "type": "object" }, "ListResponse_AuditLogResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/AuditLogResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[AuditLogResponse]", "type": "object" }, "ListResponse_CouponResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/CouponResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[CouponResponse]", "type": "object" }, "ListResponse_CreditNoteResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/CreditNoteResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[CreditNoteResponse]", "type": "object" }, "ListResponse_CustomerResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/CustomerResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[CustomerResponse]", "type": "object" }, "ListResponse_DisputeResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/DisputeResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[DisputeResponse]", "type": "object" }, "ListResponse_EventResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/EventResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[EventResponse]", "type": "object" }, "ListResponse_InvoiceResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/InvoiceResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[InvoiceResponse]", "type": "object" }, "ListResponse_OneShotPaymentResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/OneShotPaymentResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[OneShotPaymentResponse]", "type": "object" }, "ListResponse_PaymentResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/PaymentResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[PaymentResponse]", "type": "object" }, "ListResponse_PriceResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/PriceResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[PriceResponse]", "type": "object" }, "ListResponse_ProductResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/ProductResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[ProductResponse]", "type": "object" }, "ListResponse_RefundResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/RefundResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[RefundResponse]", "type": "object" }, "ListResponse_SubscriptionResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/SubscriptionResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[SubscriptionResponse]", "type": "object" }, "ListResponse_TaxRateResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/TaxRateResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[TaxRateResponse]", "type": "object" }, "ListResponse_TestClockResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/TestClockResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[TestClockResponse]", "type": "object" }, "ListResponse_UsageRecordResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/UsageRecordResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[UsageRecordResponse]", "type": "object" }, "ListResponse_WebhookDeliveryResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/WebhookDeliveryResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[WebhookDeliveryResponse]", "type": "object" }, "ListResponse_WebhookEndpointResponse_": { "properties": { "data": { "description": "The objects on this page of results.", "items": { "$ref": "#/components/schemas/WebhookEndpointResponse" }, "title": "Data", "type": "array" }, "has_more": { "default": false, "description": "Whether more results exist after this page. On a paginated list, pass the last id in data as starting_after to fetch them.", "title": "Has More", "type": "boolean" }, "object": { "const": "list", "default": "list", "description": "String representing the object's type. Always list.", "title": "Object", "type": "string" } }, "required": [ "object", "data", "has_more" ], "title": "ListResponse[WebhookEndpointResponse]", "type": "object" }, "OneShotPaymentCreate": { "additionalProperties": false, "description": "Parameters for a single payment with no subscription and no mandate.", "properties": { "amount_cents": { "description": "Amount in minor units of currency. Gross or net according to tax_behavior; the response's amount_cents is what is actually charged.", "exclusiveMinimum": 0.0, "maximum": 99999999.0, "title": "Amount Cents", "type": "integer" }, "cancel_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Where the payer is sent if they leave without paying. Optional.", "title": "Cancel Url" }, "currency": { "description": "Three-letter ISO 4217 currency code. Case-insensitive; stored uppercase.", "maxLength": 3, "minLength": 3, "title": "Currency", "type": "string" }, "customer_id": { "description": "Id of the customer being charged.", "maxLength": 64, "title": "Customer Id", "type": "string" }, "description": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "What is being paid for. Shown on the payment page and the payer's bank statement, and used as the invoice line.", "title": "Description" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Key-value pairs stored on the payment and echoed on it and its events.", "title": "Metadata" }, "payment_method": { "anyOf": [ { "enum": [ "creditcard", "ideal", "bancontact", "eps", "applepay", "paypal", "banktransfer" ], "type": "string" }, { "type": "null" } ], "description": "The payment method to charge with, checked against the methods your account can accept in this currency. Required when ui_mode is hosted; must be omitted when it is embedded, where the buyer picks the method.", "title": "Payment Method" }, "refund_window_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Days after the payment settles during which it can be refunded. Null uses the default of 30 days; 0 disables refunds.", "title": "Refund Window Days" }, "success_url": { "description": "Where the payer is sent after the payment.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Success Url", "type": "string" }, "tax_behavior": { "anyOf": [ { "enum": [ "inclusive", "exclusive" ], "type": "string" }, { "type": "null" } ], "description": "inclusive: amount_cents includes VAT. exclusive: VAT is added on top of amount_cents. Null uses the default of the tax rate for the customer's country.", "title": "Tax Behavior" }, "ui_mode": { "default": "hosted", "description": "hosted creates the payment now and returns a redirect_url for the payer. embedded creates no payment yet and returns a client_secret for the embedded payment element.", "enum": [ "hosted", "embedded" ], "title": "Ui Mode", "type": "string" } }, "required": [ "customer_id", "amount_cents", "currency", "success_url" ], "title": "OneShotPaymentCreate", "type": "object" }, "OneShotPaymentFailedEvent": { "description": "The body of a `one_shot_payment.failed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/OneShotPaymentResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "one_shot_payment.failed", "description": "What happened. Always `one_shot_payment.failed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "OneShotPaymentFailedEvent", "type": "object" }, "OneShotPaymentRefundedEvent": { "description": "The body of a `one_shot_payment.refunded` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/OneShotPaymentResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "one_shot_payment.refunded", "description": "What happened. Always `one_shot_payment.refunded` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "OneShotPaymentRefundedEvent", "type": "object" }, "OneShotPaymentResponse": { "properties": { "amount_cents": { "description": "Gross amount charged, VAT included, in minor units of currency.", "title": "Amount Cents", "type": "integer" }, "amount_disputed_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount held by open disputes, in minor units of currency, already subtracted from amount_refundable_cents. Set on every read, in webhook event payloads and in the data export.", "title": "Amount Disputed Cents" }, "amount_refundable_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount still refundable, in minor units of currency: 0 unless status is paid, and net of refunds and open disputes. Ignores the refund window. Set on every read, in webhook event payloads and in the data export.", "title": "Amount Refundable Cents" }, "amount_refunded_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total of pending and succeeded refunds, in minor units of currency. Set on every read, in webhook event payloads and in the data export.", "title": "Amount Refunded Cents" }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the payer is sent if they leave without paying, if set.", "title": "Cancel Url" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secret for mounting the embedded payment element. Returned only by the request that creates an embedded payment; null on every read.", "title": "Client Secret" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "customer_id": { "description": "Id of the customer being charged.", "title": "Customer Id", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What is being paid for, as sent at creation.", "title": "Description" }, "expires_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When an open payment stops being payable, in Unix seconds. On an unconfirmed embedded payment, when its client_secret stops working.", "title": "Expires At" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The provider's failure code for a failed payment, such as a card decline reason or a SEPA bank reason code. Null when none was given.", "title": "Failure Reason" }, "id": { "description": "Unique identifier for the one-shot payment, prefixed osp_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "default": {}, "description": "Key-value pairs set at creation. Always an object, empty when none were set.", "title": "Metadata", "type": "object" }, "net_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount before VAT, in minor units of currency. Null when no tax was computed.", "title": "Net Cents" }, "object": { "const": "one_shot_payment", "default": "one_shot_payment", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "paid_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the payment settled, in Unix seconds. Null until then.", "title": "Paid At" }, "payment_method": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, { "type": "null" } ], "description": "The payment method charged. Null on an embedded payment until the buyer confirms.", "title": "Payment Method" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment page to redirect the payer to. Null on an embedded payment.", "title": "Redirect Url" }, "status": { "description": "open, pending or authorized before settlement; then paid, failed, expired or canceled. refunded once the full amount has been refunded.", "title": "Status", "type": "string", "x-extensible-enum": [ "open", "pending", "authorized", "paid", "failed", "expired", "canceled", "refunded" ] }, "success_url": { "description": "Where the payer is sent after the payment.", "title": "Success Url", "type": "string" }, "tax_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "VAT included in amount_cents, in minor units of currency. Null when no tax was computed: no customer country, or no rate for it.", "title": "Tax Cents" }, "tax_reverse_charged": { "default": false, "description": "True when a valid VAT number from another country means the customer self-accounts for VAT, so none was charged.", "title": "Tax Reverse Charged", "type": "boolean" }, "ui_mode": { "default": "hosted", "description": "hosted or embedded, as requested at creation.", "title": "Ui Mode", "type": "string", "x-extensible-enum": [ "hosted", "embedded" ] } }, "required": [ "id", "object", "created", "livemode", "customer_id", "amount_cents", "currency", "status", "payment_method", "ui_mode", "client_secret", "description", "success_url", "cancel_url", "redirect_url", "expires_at", "paid_at", "failure_reason", "metadata", "amount_refunded_cents", "amount_refundable_cents", "amount_disputed_cents", "net_cents", "tax_cents", "tax_reverse_charged" ], "title": "OneShotPaymentResponse", "type": "object" }, "OneShotPaymentSucceededEvent": { "description": "The body of a `one_shot_payment.succeeded` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/OneShotPaymentResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "one_shot_payment.succeeded", "description": "What happened. Always `one_shot_payment.succeeded` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "OneShotPaymentSucceededEvent", "type": "object" }, "PaymentFailedEvent": { "description": "The body of a `payment.failed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/PaymentResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "payment.failed", "description": "What happened. Always `payment.failed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "PaymentFailedEvent", "type": "object" }, "PaymentResponse": { "properties": { "amount_cents": { "description": "Amount charged including tax, in minor units of currency.", "title": "Amount Cents", "type": "integer" }, "amount_disputed_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount open chargebacks have pulled back, in minor units of currency. Already subtracted from amount_refundable_cents. Set on every read, in event payloads and in the data export.", "title": "Amount Disputed Cents" }, "amount_refundable_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Balance still refundable, in minor units of currency: the charge less refunds and open disputes, or 0 when the payment cannot be refunded. Does not apply the refund window or price policy, so a refund can still be refused. Set on every read, in event payloads and in the data export.", "title": "Amount Refundable Cents" }, "amount_refunded_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total of this payment's pending and succeeded refunds, in minor units of currency. Set on every read, in event payloads and in the data export.", "title": "Amount Refunded Cents" }, "checkout_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Checkout session that started this charge. Null for a charge BillKit made on its own, such as a renewal.", "title": "Checkout Session Id" }, "coupon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The coupon that discounted this charge. Null when none did.", "title": "Coupon Id" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedCustomer" }, { "type": "null" } ], "description": "A summary of the customer. Null unless the request asked for expand=customer." }, "customer_id": { "description": "The customer who was charged.", "title": "Customer Id", "type": "string" }, "discount_cents": { "default": 0, "description": "Amount a coupon took off this charge, including tax, in minor units of currency. amount_cents plus discount_cents is the undiscounted charge. 0 when no coupon applied.", "title": "Discount Cents", "type": "integer" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the charge failed, as reported by the payment provider or recorded by BillKit. Null when no failure was recorded.", "title": "Failure Reason" }, "id": { "description": "Unique identifier for the payment.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "payment", "default": "payment", "description": "String representing the object's type. Always payment.", "title": "Object", "type": "string" }, "paid_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the charge was paid, in Unix seconds. Null until it is.", "title": "Paid At" }, "payment_method": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, { "type": "null" } ], "description": "How the charge was collected, such as creditcard, ideal or directdebit, recorded when it was made. Null when not known.", "title": "Payment Method" }, "refund_eligibility": { "anyOf": [ { "$ref": "#/components/schemas/RefundEligibilityView" }, { "type": "null" } ], "description": "Whether a refund would succeed now and for how much, applying the refund window and price policy. Null unless a retrieve asked for expand=refund_eligibility." }, "status": { "description": "The provider's status for the charge: open, pending, authorized, paid, failed, expired or canceled.", "title": "Status", "type": "string", "x-extensible-enum": [ "open", "pending", "authorized", "paid", "failed", "expired", "canceled" ] }, "subscription": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedSubscription" }, { "type": "null" } ], "description": "A summary of the subscription. Null unless the request asked for expand=subscription, or the payment has none." }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription this charge was made for. Null when it is not tied to a subscription.", "title": "Subscription Id" }, "type": { "description": "Why the charge was made: initial (first payment), renewal, plan_change, reauthorization (a new payment method) or import_activation (first charge of an imported subscription).", "title": "Type", "type": "string", "x-extensible-enum": [ "initial", "renewal", "plan_change", "reauthorization", "import_activation", "setup", "metered_cycle" ] } }, "required": [ "id", "object", "created", "livemode", "subscription_id", "customer_id", "checkout_session_id", "amount_cents", "currency", "status", "type", "paid_at", "failure_reason", "amount_refunded_cents", "amount_refundable_cents", "amount_disputed_cents", "payment_method", "discount_cents", "coupon_id", "customer", "subscription", "refund_eligibility" ], "title": "PaymentResponse", "type": "object" }, "PaymentSucceededEvent": { "description": "The body of a `payment.succeeded` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/PaymentResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "payment.succeeded", "description": "What happened. Always `payment.succeeded` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "PaymentSucceededEvent", "type": "object" }, "PingResponse": { "description": "What ``GET /v1/ping`` answers: the account and mode a key resolves to.", "properties": { "mode": { "description": "The mode the key works in, taken from its prefix: live for bk_live_, test for bk_test_.", "title": "Mode", "type": "string", "x-extensible-enum": [ "live", "test" ] }, "object": { "const": "ping", "default": "ping", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "tenant_id": { "description": "Id of the account the key belongs to, a UUID.", "title": "Tenant Id", "type": "string" } }, "required": [ "object", "tenant_id", "mode" ], "title": "PingResponse", "type": "object" }, "PlanChangePreviewRequest": { "additionalProperties": false, "properties": { "target_price_id": { "description": "Id of the price to quote a move to. It and its product must be active, in the subscription's currency and not metered, and it must differ from the current price.", "title": "Target Price Id", "type": "string" } }, "required": [ "target_price_id" ], "title": "PlanChangePreviewRequest", "type": "object" }, "PlanChangePreviewResponse": { "properties": { "charge_cents": { "description": "Total that would be charged now, VAT included, in minor units of currency: charge_net_cents plus charge_tax_cents. Not chargeable when refused is true.", "title": "Charge Cents", "type": "integer" }, "charge_net_cents": { "description": "The charge before VAT, in minor units of currency: one period of the target price, net of VAT and of any coupon that carries onto it, less credit_cents.", "title": "Charge Net Cents", "type": "integer" }, "charge_tax_cents": { "description": "VAT on charge_net_cents, in minor units of currency.", "title": "Charge Tax Cents", "type": "integer" }, "credit_cents": { "description": "Credit for the unused part of the current period, before VAT, in minor units of currency: the unused share of what the period was actually paid.", "title": "Credit Cents", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "new_period_end": { "description": "Where the new period would end, in Unix seconds: one interval of the target price after proration_at.", "title": "New Period End", "type": "integer" }, "object": { "const": "plan_change_preview", "default": "plan_change_preview", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "proration_at": { "description": "The instant the quote values the change at, in Unix seconds.", "title": "Proration At", "type": "integer" }, "refusal_reason": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "renewal_imminent", "downgrade_not_supported" ] }, { "type": "null" } ], "description": "Why the change would be refused: renewal_imminent when the charge would be under the minimum because the renewal is close (wait for it), downgrade_not_supported when the credit exceeds the target price. Null when refused is false.", "title": "Refusal Reason" }, "refused": { "description": "Whether the change would be refused if requested now. See refusal_reason.", "title": "Refused", "type": "boolean" }, "target_price_cents": { "description": "The target price's amount_cents as listed, before any coupon, in minor units of currency.", "title": "Target Price Cents", "type": "integer" }, "target_price_id": { "description": "Id of the price the quote is for.", "title": "Target Price Id", "type": "string" } }, "required": [ "object", "target_price_id", "target_price_cents", "currency", "credit_cents", "charge_cents", "charge_net_cents", "charge_tax_cents", "refused", "refusal_reason", "proration_at", "new_period_end" ], "title": "PlanChangePreviewResponse", "type": "object" }, "PlanChangeUpdateRequest": { "additionalProperties": false, "properties": { "target_price_id": { "description": "Id of the price to move the subscription to. It and its product must be active, in the subscription's currency and not metered, and it must differ from the current price.", "title": "Target Price Id", "type": "string" } }, "required": [ "target_price_id" ], "title": "PlanChangeUpdateRequest", "type": "object" }, "PortalTenantCapabilities": { "properties": { "checkout_header": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the embedded checkout element shows its own header with your logo, name, product and amount. Defaults to true.", "title": "Checkout Header" }, "coupons": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether customers can enter a coupon code in the portal. Defaults to false; the code also needs a product that allows promotion codes.", "title": "Coupons" }, "customer_country_editable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether customers can change their country in the portal. Your own API and console updates are not affected. Defaults to true.", "title": "Customer Country Editable" }, "customer_vat_number_editable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether customers can change their VAT number in the portal. Your own API and console updates are not affected. Defaults to true.", "title": "Customer Vat Number Editable" }, "cycle_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether customers can switch billing interval in the portal. When false, only prices on the subscription's current interval are offered. Defaults to true.", "title": "Cycle Enabled" }, "invoice_pdf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the portal offers invoice PDF downloads. Defaults to true.", "title": "Invoice Pdf" }, "powered_by": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the portal and invoice PDFs show a Powered by BillKit line. Defaults to true.", "title": "Powered By" }, "show_features": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the portal lists the product's marketing_features. Defaults to true.", "title": "Show Features" } }, "title": "PortalTenantCapabilities", "type": "object" }, "PortalTenantTheme-Input": { "additionalProperties": true, "properties": { "display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CSS font-family for headings, with the same rules as font.", "title": "Display" }, "font": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CSS font-family list for body text, such as Inter, sans-serif. The portal ignores a value containing anything but letters, digits, spaces, commas, quotes, underscores and hyphens.", "title": "Font" }, "on_primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text colour on primary. Black or white, whichever is legible, when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "On Primary" }, "palette": { "anyOf": [ { "enum": [ "studio", "blank" ], "type": "string" }, { "type": "null" } ], "description": "Base look the brand colours are layered over: studio (BillKit's default) or blank, a plain canvas. Null uses studio.", "title": "Palette" }, "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand colour for buttons and highlights. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary" }, "primary_100": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Light brand tint, used as a background. Derived from primary when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 100" }, "primary_50": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lightest brand tint, used as a background. Derived from primary when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 50" }, "primary_600": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand colour used as text, such as links. Derived from primary for legibility when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 600" }, "radius": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Corner radius in pixels. The portal ignores a value above 128.", "title": "Radius" }, "stub_a": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Light end of the gradient on the subscription card. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Stub A" }, "stub_b": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dark end of the gradient on the subscription card. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Stub B" } }, "title": "PortalTenantTheme", "type": "object" }, "PortalTenantTheme-Output": { "additionalProperties": true, "properties": { "display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CSS font-family for headings, with the same rules as font.", "title": "Display" }, "font": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CSS font-family list for body text, such as Inter, sans-serif. The portal ignores a value containing anything but letters, digits, spaces, commas, quotes, underscores and hyphens.", "title": "Font" }, "on_primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text colour on primary. Black or white, whichever is legible, when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "On Primary" }, "palette": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "studio", "blank" ] }, { "type": "null" } ], "description": "Base look the brand colours are layered over: studio (BillKit's default) or blank, a plain canvas. Null uses studio.", "title": "Palette" }, "primary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand colour for buttons and highlights. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary" }, "primary_100": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Light brand tint, used as a background. Derived from primary when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 100" }, "primary_50": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lightest brand tint, used as a background. Derived from primary when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 50" }, "primary_600": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand colour used as text, such as links. Derived from primary for legibility when unset. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Primary 600" }, "radius": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Corner radius in pixels. The portal ignores a value above 128.", "title": "Radius" }, "stub_a": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Light end of the gradient on the subscription card. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Stub A" }, "stub_b": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dark end of the gradient on the subscription card. A CSS colour: hex, rgb(), hsl() or a colour name. The portal ignores any other value.", "title": "Stub B" } }, "required": [ "palette", "primary", "primary_600", "primary_50", "primary_100", "on_primary", "stub_a", "stub_b", "radius", "font", "display" ], "title": "PortalTenantTheme", "type": "object" }, "PriceArchivedEvent": { "description": "The body of a `price.archived` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/PriceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "price.archived", "description": "What happened. Always `price.archived` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "PriceArchivedEvent", "type": "object" }, "PriceCreate": { "additionalProperties": false, "properties": { "amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Amount charged each period, in minor units of currency. On a metered price it is the per-unit rate. Must be positive. Send exactly one of amount_cents and unit_amount_decimal, or neither on a tiered price.", "title": "Amount Cents" }, "billing_scheme": { "default": "per_unit", "description": "per_unit multiplies one rate by the quantity. tiered prices the quantity by tiers and is for metered prices only.", "enum": [ "per_unit", "tiered" ], "title": "Billing Scheme", "type": "string" }, "currency": { "default": "EUR", "description": "Three-letter ISO 4217 currency code, stored uppercase. Must be one of the currencies enabled for your account.", "maxLength": 3, "minLength": 3, "title": "Currency", "type": "string" }, "interval": { "description": "How often the price is charged. Metered prices must use month.", "enum": [ "month", "year" ], "title": "Interval", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Key-value pairs stored on the price and returned with it.", "title": "Metadata" }, "payment_methods": { "anyOf": [ { "items": { "enum": [ "creditcard", "directdebit", "ideal", "eps", "applepay", "paypal" ], "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "Payment methods offered at checkout for this price, overriding your account's. Leave it out to follow your account: the price then offers every method you have on in Mollie and have not switched off in your account settings. Must include at least one method that can make the first payment (not only directdebit).", "title": "Payment Methods" }, "product_id": { "description": "The product this price belongs to. It must be active.", "maxLength": 64, "minLength": 1, "title": "Product Id", "type": "string" }, "refund_on_cancel": { "default": "none", "description": "What a cancellation refunds, against the most recent charge. 'none' (default) refunds nothing. 'full' refunds the whole charge and ends access immediately. 'prorated' refunds the unused part of the current period and also ends access. Both are still bounded by the refund window below. Metered prices must leave this at 'none': ending access mid-period would strand usage that has not been billed yet.", "enum": [ "none", "full", "prorated" ], "title": "Refund On Cancel", "type": "string" }, "refund_window_initial_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Days after the first charge (or a plan change onto this price) during which it can be refunded. 0 disables refunds of that charge. Null uses the default: 7 days on a monthly price, 30 on a yearly one.", "title": "Refund Window Initial Days" }, "refund_window_renewal_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Days after a renewal charge during which it can be refunded. 0 disables refunds of renewals. Null uses the default of 3 days.", "title": "Refund Window Renewal Days" }, "tax_behavior": { "default": "unspecified", "description": "Whether amount_cents includes VAT (inclusive) or has it added on top (exclusive). unspecified follows the inclusive setting of the tax rate for the customer's country, and is inclusive when there is none.", "enum": [ "inclusive", "exclusive", "unspecified" ], "title": "Tax Behavior", "type": "string" }, "tiers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PriceTierInput" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "The pricing bands, in increasing order. Required when billing_scheme is tiered, refused otherwise.", "title": "Tiers" }, "tiers_mode": { "anyOf": [ { "enum": [ "graduated", "volume" ], "type": "string" }, { "type": "null" } ], "description": "Required when billing_scheme is tiered, refused otherwise. graduated prices the units inside each band at that band's rate; volume picks one band from the total quantity and prices every unit at it.", "title": "Tiers Mode" }, "trial_days": { "default": 0, "description": "Length of the free trial a new subscription starts with, in days. Metered prices take 0.", "maximum": 90.0, "minimum": 0.0, "title": "Trial Days", "type": "integer" }, "trial_verification_cents": { "default": 100, "description": "Amount in minor units charged at checkout instead of the price when the checkout only sets up the payment mandate: during a trial, and on every metered price.", "maximum": 99999999.0, "minimum": 0.0, "title": "Trial Verification Cents", "type": "integer" }, "unit_amount_decimal": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "Per-unit rate in minor units with up to 12 decimal places, as a string ('0.02' means 0.02 cents). Metered prices only, and mutually exclusive with amount_cents. Always a string: a JSON number cannot hold this value exactly.", "title": "Unit Amount Decimal" }, "usage_type": { "default": "licensed", "description": "licensed charges amount_cents every period. metered bills reported usage at the end of each monthly period, and checkout charges only trial_verification_cents.", "enum": [ "licensed", "metered" ], "title": "Usage Type", "type": "string" } }, "required": [ "product_id", "interval" ], "title": "PriceCreate", "type": "object" }, "PriceCreatedEvent": { "description": "The body of a `price.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/PriceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "price.created", "description": "What happened. Always `price.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "PriceCreatedEvent", "type": "object" }, "PriceResponse": { "properties": { "active": { "description": "Whether the price can be used for new checkouts. False once archived.", "title": "Active", "type": "boolean" }, "amount_cents": { "description": "Amount in minor units of currency: charged each period on a licensed price, the per-unit rate on a metered one. With a decimal rate this is that rate rounded, and can be 0. 0 on a tiered price.", "title": "Amount Cents", "type": "integer" }, "billing_scheme": { "description": "per_unit multiplies one rate by the quantity; tiered prices it by tiers.", "title": "Billing Scheme", "type": "string", "x-extensible-enum": [ "per_unit", "tiered" ] }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "id": { "description": "Unique identifier for the price, prefixed price_.", "title": "Id", "type": "string" }, "interval": { "description": "How often the price is charged.", "title": "Interval", "type": "string", "x-extensible-enum": [ "month", "year" ] }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value pairs attached to the price.", "title": "Metadata", "type": "object" }, "object": { "const": "price", "default": "price", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "payment_methods": { "description": "Payment methods offered at checkout for this price. When payment_methods_from_account is true this is every method your account has not switched off, and a checkout offers the ones among them that you have on in Mollie.", "items": { "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "ideal", "bancontact", "eps", "banktransfer", "applepay", "paypal" ] }, "title": "Payment Methods", "type": "array" }, "payment_methods_from_account": { "description": "True when the price follows your account's payment methods, false when it has its own list. Send payment_methods: null on an update to make it follow your account again.", "title": "Payment Methods From Account", "type": "boolean" }, "product_id": { "description": "The product this price belongs to.", "title": "Product Id", "type": "string" }, "product_name": { "description": "Name of the product this price belongs to.", "title": "Product Name", "type": "string" }, "refund_on_cancel": { "description": "What a cancellation refunds against the most recent charge.", "title": "Refund On Cancel", "type": "string", "x-extensible-enum": [ "none", "full", "prorated" ] }, "refund_window_initial_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Refund window for the first charge, in days. 0 means not refundable; null means the default (7 days monthly, 30 yearly).", "title": "Refund Window Initial Days" }, "refund_window_renewal_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Refund window for renewal charges, in days. 0 means not refundable; null means the default of 3 days.", "title": "Refund Window Renewal Days" }, "tax_behavior": { "description": "Whether amount_cents includes VAT (inclusive) or has it added on top (exclusive). unspecified follows the tax rate for the customer's country, and is inclusive when there is none.", "title": "Tax Behavior", "type": "string", "x-extensible-enum": [ "inclusive", "exclusive", "unspecified" ] }, "tiers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PriceTier" }, "type": "array" }, { "type": "null" } ], "description": "The pricing bands. Null on a per-unit price.", "title": "Tiers" }, "tiers_mode": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "graduated", "volume" ] }, { "type": "null" } ], "description": "How tiers price a quantity: graduated or volume. Null on a per-unit price.", "title": "Tiers Mode" }, "trial_days": { "description": "Length of the free trial a new subscription starts with, in days.", "title": "Trial Days", "type": "integer" }, "trial_verification_cents": { "description": "Amount in minor units charged at checkout to set up the payment mandate, during a trial and on a metered price.", "title": "Trial Verification Cents", "type": "integer" }, "unit_amount_decimal": { "description": "The per-unit rate actually charged, in minor units, as a decimal string: the declared decimal rate, or amount_cents written as an integer. Do not parse it into a float.", "title": "Unit Amount Decimal", "type": "string" }, "usage_type": { "description": "licensed charges amount_cents every period; metered bills reported usage.", "title": "Usage Type", "type": "string", "x-extensible-enum": [ "licensed", "metered" ] } }, "required": [ "id", "object", "created", "livemode", "product_id", "product_name", "amount_cents", "unit_amount_decimal", "currency", "interval", "active", "metadata", "trial_days", "trial_verification_cents", "payment_methods", "refund_on_cancel", "refund_window_initial_days", "refund_window_renewal_days", "tax_behavior", "usage_type", "billing_scheme", "tiers_mode", "tiers" ], "title": "PriceResponse", "type": "object" }, "PriceTier": { "description": "One band of a tiered price. ``up_to: null`` marks the open-ended last band.", "properties": { "flat_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Amount in minor units charged once when the quantity reaches this band, or null.", "title": "Flat Amount Cents" }, "unit_amount_decimal": { "description": "Per-unit rate for this band in minor units, as a decimal string. \"0\" when the band has no per-unit rate.", "title": "Unit Amount Decimal", "type": "string" }, "up_to": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Inclusive upper bound of this band, in units. Null on the open-ended last band.", "title": "Up To" } }, "required": [ "up_to", "unit_amount_decimal", "flat_amount_cents" ], "title": "PriceTier", "type": "object" }, "PriceTierInput": { "additionalProperties": false, "description": "One band of a tiered price.\n\n``up_to`` is the inclusive upper bound of the band; bands must strictly\nincrease and the last one must be ``\"inf\"``. A band sets a per-unit rate\n(``unit_amount_cents`` in whole minor units, or ``unit_amount_decimal``\nas a string for finer rates), a ``flat_amount_cents`` charged once for\nreaching the band, or both. Write a free band as ``unit_amount_cents: 0``.", "properties": { "flat_amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Amount in minor units charged once when the quantity reaches this band.", "title": "Flat Amount Cents" }, "unit_amount_cents": { "anyOf": [ { "maximum": 99999999.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Per-unit rate for this band in whole minor units. Send this or unit_amount_decimal, not both; a band with neither needs flat_amount_cents.", "title": "Unit Amount Cents" }, "unit_amount_decimal": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "Per-unit rate for this band in minor units with up to 12 decimal places, as a string. Send this or unit_amount_cents, not both.", "title": "Unit Amount Decimal" }, "up_to": { "anyOf": [ { "maximum": 9007199254740991.0, "type": "integer" }, { "const": "inf", "type": "string" } ], "description": "Inclusive upper bound of this band, in units. Bands must strictly increase, and the last band must be inf.", "title": "Up To" } }, "required": [ "up_to" ], "title": "PriceTierInput", "type": "object" }, "PriceUpdate": { "additionalProperties": false, "description": "The price settings that can change after creation. Omitted fields are left alone.", "properties": { "active": { "description": "false archives the price: new checkouts and plan changes cannot use it, and existing subscriptions keep renewing on it. true restores it.", "title": "Active", "type": "boolean" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Replaces the stored metadata whole. Send {} to empty it.", "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "title": "Metadata", "type": "object" }, "payment_methods": { "anyOf": [ { "items": { "enum": [ "creditcard", "directdebit", "ideal", "eps", "applepay", "paypal" ], "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "Payment methods offered at checkout for this price, overriding your account's. Send null to go back to following your account. Must include at least one method that can make the first payment (not only directdebit).", "title": "Payment Methods" }, "refund_on_cancel": { "description": "What a cancellation refunds against the most recent charge: none, full or prorated. Applies to customers already on the price. Metered prices must keep none.", "enum": [ "none", "full", "prorated" ], "title": "Refund On Cancel", "type": "string" }, "refund_window_initial_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Refund window for the first charge, in days. 0 disables refunds of that charge; null goes back to the default (7 days monthly, 30 yearly).", "title": "Refund Window Initial Days" }, "refund_window_renewal_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Refund window for renewal charges, in days. 0 disables refunds of renewals; null goes back to the default of 3 days.", "title": "Refund Window Renewal Days" }, "tax_behavior": { "description": "Can be set only while the price's tax_behavior is unspecified, and not changed after.", "enum": [ "inclusive", "exclusive" ], "title": "Tax Behavior", "type": "string" } }, "title": "PriceUpdate", "type": "object" }, "PriceUpdatedEvent": { "description": "The body of a `price.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/PriceResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "price.updated", "description": "What happened. Always `price.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "PriceUpdatedEvent", "type": "object" }, "ProductArchivedEvent": { "description": "The body of a `product.archived` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/ProductResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "product.archived", "description": "What happened. Always `product.archived` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "ProductArchivedEvent", "type": "object" }, "ProductCreate": { "additionalProperties": false, "properties": { "allow_promotion_codes": { "default": false, "description": "Whether a buyer may enter a coupon code at checkout for this product's prices. A coupon_code you pass when creating the checkout session applies either way.", "title": "Allow Promotion Codes", "type": "boolean" }, "description": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Longer description of the product, shown in the billing portal.", "title": "Description" }, "marketing_features": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 24, "type": "array" }, { "type": "null" } ], "description": "Up to 24 short feature lines listed under the product in the billing portal's plan picker.", "title": "Marketing Features" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Key-value pairs stored on the product and returned with it.", "title": "Metadata" }, "name": { "description": "The product's name, shown to customers at checkout and in the portal.", "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "ProductCreate", "type": "object" }, "ProductCreatedEvent": { "description": "The body of a `product.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/ProductResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "product.created", "description": "What happened. Always `product.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "ProductCreatedEvent", "type": "object" }, "ProductResponse": { "properties": { "active": { "description": "Whether the product is on sale. False once archived.", "title": "Active", "type": "boolean" }, "allow_promotion_codes": { "description": "Whether a buyer may enter a coupon code at checkout for this product's prices.", "title": "Allow Promotion Codes", "type": "boolean" }, "archived_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the product was archived, in Unix seconds. Null while it is active.", "title": "Archived At" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "default_price": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedPrice" }, { "type": "null" } ], "description": "The default price. Null unless the request asked for expand=default_price, or when none is set." }, "default_price_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The price the billing portal offers on its interval. Set to the first price created under the product; null when none is set.", "title": "Default Price Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Longer description of the product, or null.", "title": "Description" }, "id": { "description": "Unique identifier for the product, prefixed prod_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "marketing_features": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Feature lines listed in the billing portal's plan picker, or null.", "title": "Marketing Features" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value pairs attached to the product.", "title": "Metadata", "type": "object" }, "name": { "description": "The product's name, shown to customers.", "title": "Name", "type": "string" }, "object": { "const": "product", "default": "product", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "prices": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ExpandedPrice" }, "type": "array" }, { "type": "null" } ], "description": "The product's prices, archived ones included, active first then newest. Null unless the request asked for expand=prices.", "title": "Prices" }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/ProductStats" }, { "type": "null" } ], "description": "Subscriber and revenue figures. Null unless the request asked for expand=stats." } }, "required": [ "id", "object", "created", "livemode", "name", "description", "marketing_features", "metadata", "active", "allow_promotion_codes", "default_price_id", "archived_at", "prices", "stats", "default_price" ], "title": "ProductResponse", "type": "object" }, "ProductStats": { "description": "Current subscribers and monthly recurring revenue for a product.\n\n``subscriber_count`` and ``mrr_cents`` cover ``active`` and ``trialing``\nsubscriptions on any of the product's prices. ``mrr_cents`` counts yearly\nprices at a twelfth, applies recurring coupons, excludes metered prices\nand ignores tax; it is a display figure, not an accounting one.\n``currency`` is the currency of ``mrr_cents``, or null when the\ncontributing subscriptions use more than one.\n``active_price_count`` is the number of active prices.", "properties": { "active_price_count": { "description": "Number of the product's prices that are active.", "title": "Active Price Count", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of mrr_cents, or null when the subscriptions use more than one.", "title": "Currency" }, "mrr_cents": { "description": "Monthly recurring revenue of those subscriptions in minor units of currency: yearly prices at a twelfth, recurring coupons applied, metered prices and tax left out.", "title": "Mrr Cents", "type": "integer" }, "object": { "const": "product.stats", "default": "product.stats", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "subscriber_count": { "description": "Number of active and trialing subscriptions on any of the product's prices.", "title": "Subscriber Count", "type": "integer" } }, "required": [ "object", "subscriber_count", "mrr_cents", "currency", "active_price_count" ], "title": "ProductStats", "type": "object" }, "ProductUpdate": { "additionalProperties": false, "description": "The product fields to change. Omitted fields are left alone.\n\n``description``, ``marketing_features`` and ``default_price_id`` are\ncleared with ``null``. ``name``, ``metadata``, ``active`` and\n``allow_promotion_codes`` cannot be cleared and refuse ``null`` with a\n400. ``metadata`` replaces the stored object whole; send ``{}`` to\nempty it.", "properties": { "active": { "description": "false archives the product: its prices cannot be used for new checkouts or plan changes, and no new price can be created under it. Existing subscriptions keep renewing. true restores it.", "title": "Active", "type": "boolean" }, "allow_promotion_codes": { "description": "Whether a buyer may enter a coupon code at checkout for this product's prices.", "title": "Allow Promotion Codes", "type": "boolean" }, "default_price_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "An active price of this product, offered by the billing portal on its interval. null clears it.", "title": "Default Price Id" }, "description": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "Longer description of the product. null clears it.", "title": "Description" }, "marketing_features": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 24, "type": "array" }, { "type": "null" } ], "description": "Feature lines listed in the billing portal's plan picker. Replaces the list whole; null clears it.", "title": "Marketing Features" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Replaces the stored metadata whole. Send {} to empty it.", "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "title": "Metadata", "type": "object" }, "name": { "description": "The product's name, shown to customers.", "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "title": "ProductUpdate", "type": "object" }, "ProductUpdatedEvent": { "description": "The body of a `product.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/ProductResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "product.updated", "description": "What happened. Always `product.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "ProductUpdatedEvent", "type": "object" }, "ProviderPayloadResponse": { "properties": { "available": { "description": "Whether the provider's record could be fetched. When false, payload is null and unavailable_reason says why.", "title": "Available", "type": "boolean" }, "object": { "const": "payment.provider_payload", "default": "payment.provider_payload", "description": "String representing the object's type. Always payment.provider_payload.", "title": "Object", "type": "string" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The provider's record of the charge, verbatim and unmapped. Its shape is the provider's and can change; read it as a diagnostic. Null when available is false.", "title": "Payload" }, "provider": { "description": "The payment provider that holds the charge, such as mollie.", "title": "Provider", "type": "string" }, "provider_payment_id": { "description": "The provider's id for the charge.", "title": "Provider Payment Id", "type": "string" }, "redacted": { "default": false, "description": "True when the payment's customer was purged: payload then keeps only amounts, statuses, timestamps and identifiers, with personal fields removed.", "title": "Redacted", "type": "boolean" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the record could not be fetched, as a sentence. Null when available is true.", "title": "Unavailable Reason" } }, "required": [ "object", "available", "provider", "provider_payment_id", "payload", "unavailable_reason", "redacted" ], "title": "ProviderPayloadResponse", "type": "object" }, "PurgedResource": { "description": "Returned by a GDPR purge: the deletion marker, saying the data was erased too.\n\nA purged object 404s afterwards exactly like a deleted one, so the answer\nis the same marker ``DELETE`` returns rather than the object (whose\nerased placeholder email would read as live data), plus ``purged``.", "properties": { "deleted": { "const": true, "default": true, "description": "Always true.", "title": "Deleted", "type": "boolean" }, "id": { "description": "Id of the purged object.", "title": "Id", "type": "string" }, "object": { "description": "Type of the purged object, such as customer.", "title": "Object", "type": "string" }, "purged": { "const": true, "default": true, "description": "Always true: the object's personal data was erased as well.", "title": "Purged", "type": "boolean" } }, "required": [ "id", "object", "deleted", "purged" ], "title": "PurgedResource", "type": "object" }, "ReauthorizationRequest": { "additionalProperties": false, "properties": { "return_url": { "description": "Where the customer is sent after the payment page, whatever its outcome.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Return Url", "type": "string" } }, "required": [ "return_url" ], "title": "ReauthorizationRequest", "type": "object" }, "ReauthorizationResponse": { "description": "A started payment-method replacement. Send the customer to ``checkout_url``.\n\n``verification_amount_cents`` and ``verification_currency`` are the\nverification charge the customer pays to authorise the new method.\n``subscription.payment_method_updated`` is sent once the provider\nconfirms it.", "properties": { "checkout_url": { "description": "The provider's payment page. Send the customer here to authorise the new method.", "title": "Checkout Url", "type": "string" }, "object": { "const": "reauthorization", "default": "reauthorization", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "operation_id": { "description": "Identifier of the billing operation that tracks this replacement, a UUID.", "title": "Operation Id", "type": "string" }, "subscription_id": { "description": "Id of the subscription whose payment method is being replaced.", "title": "Subscription Id", "type": "string" }, "verification_amount_cents": { "description": "What the customer is charged on the payment page, in minor units of verification_currency: a small verification charge, or the unpaid renewal for a past_due subscription whose renewals BillKit charges.", "title": "Verification Amount Cents", "type": "integer" }, "verification_currency": { "description": "Three-letter ISO 4217 currency code of that charge, uppercase.", "title": "Verification Currency", "type": "string" } }, "required": [ "object", "subscription_id", "operation_id", "checkout_url", "verification_amount_cents", "verification_currency" ], "title": "ReauthorizationResponse", "type": "object" }, "RefundCreateRequest": { "additionalProperties": false, "properties": { "amount_cents": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 99999999.0, "type": "integer" }, { "type": "null" } ], "description": "Amount to refund, in minor units of currency. Omit to refund the whole remaining balance. The refund that brings the total refunded to the full charge cancels the subscription, or marks a one-off payment refunded.", "title": "Amount Cents" }, "one_shot_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The one-off payment to refund. Cannot be combined with payment_id or subscription_id.", "title": "One Shot Payment Id" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription payment to refund. One of payment_id, subscription_id or one_shot_payment_id is required.", "title": "Payment Id" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Why the refund was made. Recorded on the refund and copied to its credit note.", "title": "Reason" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Refund the subscription's most recent payment. Use when payment_id is omitted.", "title": "Subscription Id" } }, "title": "RefundCreateRequest", "type": "object" }, "RefundCreatedEvent": { "description": "The body of a `refund.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/RefundResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "refund.created", "description": "What happened. Always `refund.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "RefundCreatedEvent", "type": "object" }, "RefundEligibilityView": { "description": "Whether a refund of the remaining balance is expected to succeed now.\n\nOn a subscription it answers for the last charge; on a payment, for that\npayment. ``amount_cents`` is the refundable balance, net of earlier\nrefunds and of money an open dispute has taken back. Advisory: the\nrefund call makes the final decision under a lock, and the subscription\nform does not check for a plan change or another refund in flight.", "properties": { "amount_cents": { "description": "The refundable balance in minor units of currency, net of earlier refunds and of money an open dispute has taken back.", "title": "Amount Cents", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Three-letter ISO 4217 currency code of the charge. Null when there is no charge.", "title": "Currency" }, "days_remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Whole days left in the refund window, counting today. Null when no window applies or the window has closed.", "title": "Days Remaining" }, "eligible": { "description": "Whether a refund of the whole of amount_cents is expected to succeed now.", "title": "Eligible", "type": "boolean" }, "object": { "const": "refund_eligibility", "default": "refund_eligibility", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "reason": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "no_charge", "not_paid", "unrefundable_type", "window_expired", "fully_refunded", "disputed", "operation_pending", "plan_change_pending" ] }, { "type": "null" } ], "description": "Why a refund is not possible now. Null when eligible is true.", "title": "Reason" }, "window_ends_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the refund window closes, in Unix seconds. Null when no window applies.", "title": "Window Ends At" } }, "required": [ "object", "eligible", "amount_cents", "currency", "days_remaining", "reason", "window_ends_at" ], "title": "RefundEligibilityView", "type": "object" }, "RefundFailedEvent": { "description": "The body of a `refund.failed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/RefundResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "refund.failed", "description": "What happened. Always `refund.failed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "RefundFailedEvent", "type": "object" }, "RefundResponse": { "properties": { "amount_cents": { "description": "Amount refunded, in minor units of currency.", "title": "Amount Cents", "type": "integer" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "currency": { "description": "Three-letter ISO 4217 currency code, uppercase.", "title": "Currency", "type": "string" }, "id": { "description": "Unique identifier for the refund.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "refund", "default": "refund", "description": "String representing the object's type. Always refund.", "title": "Object", "type": "string" }, "one_shot_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The one-off payment refunded. Null when the refund is against a subscription payment.", "title": "One Shot Payment Id" }, "payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription payment refunded. Null when the refund is against a one-off payment.", "title": "Payment Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the refund was made, as given when it was created. Null when none was given.", "title": "Reason" }, "status": { "description": "One of pending, succeeded or failed. Refunds settle asynchronously: watch refund.succeeded and refund.failed.", "title": "Status", "type": "string", "x-extensible-enum": [ "pending", "succeeded", "failed" ] }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription behind the refunded payment. Null for a one-off payment.", "title": "Subscription Id" } }, "required": [ "id", "object", "created", "livemode", "payment_id", "one_shot_payment_id", "subscription_id", "amount_cents", "currency", "reason", "status" ], "title": "RefundResponse", "type": "object" }, "RefundSucceededEvent": { "description": "The body of a `refund.succeeded` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/RefundResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "refund.succeeded", "description": "What happened. Always `refund.succeeded` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "RefundSucceededEvent", "type": "object" }, "SubscriptionCanceledEvent": { "description": "The body of a `subscription.canceled` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.canceled", "description": "What happened. Always `subscription.canceled` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionCanceledEvent", "type": "object" }, "SubscriptionCouponAppliedEvent": { "description": "The body of a `subscription.coupon_applied` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.coupon_applied", "description": "What happened. Always `subscription.coupon_applied` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionCouponAppliedEvent", "type": "object" }, "SubscriptionCouponExpiredEvent": { "description": "The body of a `subscription.coupon_expired` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.coupon_expired", "description": "What happened. Always `subscription.coupon_expired` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionCouponExpiredEvent", "type": "object" }, "SubscriptionCreatedEvent": { "description": "The body of a `subscription.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.created", "description": "What happened. Always `subscription.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionCreatedEvent", "type": "object" }, "SubscriptionDiscount": { "description": "The coupon bound to a subscription's future charges.\n\nStripe's ``subscription.discount``, reduced to what BillKit stores: the\ncoupon and the end of its duration window. Read the coupon itself with\n``GET /v1/coupons/{coupon_id}``.", "properties": { "coupon_id": { "description": "Id of the coupon applied to the subscription's charges.", "title": "Coupon Id", "type": "string" }, "ends_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the discount stops applying, in Unix seconds: a charge dated at or after it is billed at list price. Null for a forever coupon, and for a once or repeating coupon until its first discounted charge, which fixes the end.", "title": "Ends At" }, "object": { "const": "discount", "default": "discount", "description": "String representing the object's type.", "title": "Object", "type": "string" } }, "required": [ "object", "coupon_id", "ends_at" ], "title": "SubscriptionDiscount", "type": "object" }, "SubscriptionPastDueEvent": { "description": "The body of a `subscription.past_due` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.past_due", "description": "What happened. Always `subscription.past_due` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionPastDueEvent", "type": "object" }, "SubscriptionPausedEvent": { "description": "The body of a `subscription.paused` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.paused", "description": "What happened. Always `subscription.paused` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionPausedEvent", "type": "object" }, "SubscriptionPaymentMethod": { "description": "What the next renewal charges: the mandate's rail and, for a card, its details.\n\nDrawn from the columns ``services.renewal_instrument`` writes with the\nmandate, so it moves exactly when the mandate does. The mandate id is\nnot exposed. Field names match the billing portal's payment method.", "properties": { "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Card brand as the provider reports it. Null for a non-card mandate or when not reported.", "title": "Brand" }, "exp_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Card expiry month, 1 to 12. Null for a non-card mandate or when not reported.", "title": "Exp Month" }, "exp_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Card expiry year, four digits. Null for a non-card mandate or when not reported.", "title": "Exp Year" }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four digits of the card. Null for a non-card mandate or when not reported.", "title": "Last4" }, "type": { "description": "The mandate's method: creditcard, directdebit (SEPA) or paypal. An iDEAL checkout mints a directdebit mandate, so it shows as directdebit.", "title": "Type", "type": "string", "x-extensible-enum": [ "creditcard", "directdebit", "paypal" ] } }, "required": [ "type", "brand", "last4", "exp_month", "exp_year" ], "title": "SubscriptionPaymentMethod", "type": "object" }, "SubscriptionPaymentMethodUpdatedEvent": { "description": "The body of a `subscription.payment_method_updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.payment_method_updated", "description": "What happened. Always `subscription.payment_method_updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionPaymentMethodUpdatedEvent", "type": "object" }, "SubscriptionPlanChangedEvent": { "description": "The body of a `subscription.plan_changed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.plan_changed", "description": "What happened. Always `subscription.plan_changed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionPlanChangedEvent", "type": "object" }, "SubscriptionReactivatedEvent": { "description": "The body of a `subscription.reactivated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.reactivated", "description": "What happened. Always `subscription.reactivated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionReactivatedEvent", "type": "object" }, "SubscriptionResponse": { "properties": { "cancel_at_period_end": { "description": "Whether the subscription has been set to end at current_period_end instead of renewing.", "title": "Cancel At Period End", "type": "boolean" }, "canceled_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the subscription ended, in Unix seconds. Null unless status is canceled.", "title": "Canceled At" }, "cancellation_reason": { "anyOf": [ { "type": "string", "x-extensible-enum": [ "refund_issued", "trial_expired_unpaid", "period_end", "payment_failed", "imported_from_stripe" ] }, { "type": "null" } ], "description": "Why the subscription ended, set by BillKit. Null unless status is canceled.", "title": "Cancellation Reason" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "current_period_end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "End of the current billing period, in Unix seconds: the next renewal date, or the trial end while trialing. Null until the first period begins.", "title": "Current Period End" }, "current_period_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Start of the current billing period, in Unix seconds. Null until the first period begins.", "title": "Current Period Start" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedCustomer" }, { "type": "null" } ], "description": "Summary of the customer. Null unless the request asked for expand=customer." }, "customer_id": { "description": "Id of the customer the subscription bills.", "title": "Customer Id", "type": "string" }, "discount": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionDiscount" }, { "type": "null" } ], "description": "The coupon applied to future charges. Null when none is." }, "dunning_attempts_notified": { "description": "Number of failed-payment notifications sent since the last successful charge. Reset to 0 when a charge succeeds.", "title": "Dunning Attempts Notified", "type": "integer" }, "dunning_last_notified_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the last failed-payment notification was sent, in Unix seconds. Null if none has been sent since the last successful charge.", "title": "Dunning Last Notified At" }, "id": { "description": "Unique identifier for the subscription, prefixed sub_.", "title": "Id", "type": "string" }, "last_payment_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When that payment settled, in Unix seconds. Null if no payment has.", "title": "Last Payment At" }, "last_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the most recent payment that settled for this subscription. Null if none has.", "title": "Last Payment Id" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "mrr_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "This subscription's monthly recurring revenue in minor units of its price's currency: a yearly price counts at a twelfth, a recurring coupon is applied, tax and metered prices are left out. Null unless the request asked for expand=price.", "title": "Mrr Cents" }, "next_charge_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "What the next renewal will charge, in minor units of the price's currency: the recurring coupon applied, then VAT added on a tax-exclusive price. Null when nothing will be charged at renewal: the subscription is canceled, paused, canceling at period end or stopped, or its price is metered (the period's usage is billed at its close).", "title": "Next Charge Amount Cents" }, "next_payment_attempt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When BillKit will retry a failed renewal, in Unix seconds. Null when no retry is scheduled: no renewal has failed, or the payment method is unusable, the decline forbids retrying or the retries are spent, so the customer has to act.", "title": "Next Payment Attempt" }, "object": { "const": "subscription", "default": "subscription", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "payment_count": { "description": "Number of payments that have settled for this subscription. A trial's verification charge counts as one.", "title": "Payment Count", "type": "integer" }, "payment_method": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPaymentMethod" }, { "type": "null" } ], "description": "The payment method the next renewal charges. Null when there is none yet, as on an imported subscription awaiting activation." }, "price": { "anyOf": [ { "$ref": "#/components/schemas/ExpandedPrice" }, { "type": "null" } ], "description": "Summary of the price and its product. Null unless the request asked for expand=price." }, "price_id": { "description": "Id of the price the subscription is billed at. A plan change moves it only once the prorated charge succeeds.", "title": "Price Id", "type": "string" }, "refund_eligibility": { "anyOf": [ { "$ref": "#/components/schemas/RefundEligibilityView" }, { "type": "null" } ], "description": "Whether the last charge can be refunded now, and how much of it. Null unless the request asked for expand=refund_eligibility." }, "renewal_state": { "description": "What happens at the end of the current period: auto_renew renews it; paused and canceling do not renew, so access ends at current_period_end unless the subscription is resumed or reactivated; stopped means it will not renew again.", "title": "Renewal State", "type": "string", "x-extensible-enum": [ "auto_renew", "paused", "canceling", "stopped" ] }, "serves_customer": { "description": "Whether the customer should have access right now. True for an active, trialing or past_due subscription that is renewing; when renewal_state is canceling, paused or stopped, true only until current_period_end. Use this rather than status to grant access.", "title": "Serves Customer", "type": "boolean" }, "status": { "description": "Where the subscription stands with its payments. A paused subscription stays active; read renewal_state for pausing and scheduled cancellation.", "title": "Status", "type": "string", "x-extensible-enum": [ "incomplete", "trialing", "active", "past_due", "canceled" ] }, "trial_end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the free trial ends or ended, in Unix seconds, and the first paid period starts. Null if the subscription had no trial.", "title": "Trial End" }, "trial_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the free trial began, in Unix seconds. Null if the subscription had no trial.", "title": "Trial Start" } }, "required": [ "id", "object", "created", "livemode", "customer_id", "price_id", "status", "renewal_state", "serves_customer", "current_period_start", "current_period_end", "cancel_at_period_end", "canceled_at", "cancellation_reason", "last_payment_id", "last_payment_at", "payment_count", "trial_start", "trial_end", "dunning_attempts_notified", "dunning_last_notified_at", "next_payment_attempt", "discount", "payment_method", "customer", "price", "mrr_cents", "refund_eligibility", "next_charge_amount_cents" ], "title": "SubscriptionResponse", "type": "object" }, "SubscriptionResumedEvent": { "description": "The body of a `subscription.resumed` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.resumed", "description": "What happened. Always `subscription.resumed` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionResumedEvent", "type": "object" }, "SubscriptionTrialEndedEvent": { "description": "The body of a `subscription.trial_ended` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.trial_ended", "description": "What happened. Always `subscription.trial_ended` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionTrialEndedEvent", "type": "object" }, "SubscriptionTrialStartedEvent": { "description": "The body of a `subscription.trial_started` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.trial_started", "description": "What happened. Always `subscription.trial_started` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionTrialStartedEvent", "type": "object" }, "SubscriptionTrialWillEndEvent": { "description": "The body of a `subscription.trial_will_end` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.trial_will_end", "description": "What happened. Always `subscription.trial_will_end` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionTrialWillEndEvent", "type": "object" }, "SubscriptionUpdatedEvent": { "description": "The body of a `subscription.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/SubscriptionResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "subscription.updated", "description": "What happened. Always `subscription.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "SubscriptionUpdatedEvent", "type": "object" }, "TaxRateCreate": { "additionalProperties": false, "properties": { "country_code": { "description": "Two-letter ISO 3166-1 country code, stored uppercase. Creating a rate retires the country's current active rate.", "maxLength": 2, "minLength": 2, "title": "Country Code", "type": "string" }, "display_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A label for the rate.", "title": "Display Name" }, "inclusive": { "default": true, "description": "Whether prices charged in this country already include the tax (true) or have it added on top (false). Applies to prices whose tax_behavior is unspecified.", "title": "Inclusive", "type": "boolean" }, "rate_basis_points": { "description": "The rate in basis points: 2100 is 21 percent.", "maximum": 10000.0, "minimum": 0.0, "title": "Rate Basis Points", "type": "integer" } }, "required": [ "country_code", "rate_basis_points" ], "title": "TaxRateCreate", "type": "object" }, "TaxRateResponse": { "properties": { "active": { "description": "Whether the rate applies to new charges. A country has at most one active rate.", "title": "Active", "type": "boolean" }, "country_code": { "description": "Two-letter ISO 3166-1 country code, uppercase, the rate applies to.", "title": "Country Code", "type": "string" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A label for the rate, or null.", "title": "Display Name" }, "id": { "description": "Unique identifier for the tax rate, prefixed tr_.", "title": "Id", "type": "string" }, "inclusive": { "description": "Whether prices charged in this country already include the tax (true) or have it added on top (false), for prices whose tax_behavior is unspecified.", "title": "Inclusive", "type": "boolean" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "tax_rate", "default": "tax_rate", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "rate_basis_points": { "description": "The rate in basis points: 2100 is 21 percent.", "title": "Rate Basis Points", "type": "integer" } }, "required": [ "id", "object", "created", "livemode", "country_code", "display_name", "rate_basis_points", "inclusive", "active" ], "title": "TaxRateResponse", "type": "object" }, "TaxRateUpdate": { "additionalProperties": false, "description": "The tax rate fields to change. Omitted fields are left alone.\n\n``display_name`` is cleared with ``null``. ``rate_basis_points``,\n``inclusive`` and ``active`` cannot be cleared and refuse ``null`` with\na 400.", "properties": { "active": { "description": "false stops the rate applying to new charges. true reactivates it and retires any other active rate for the same country.", "title": "Active", "type": "boolean" }, "display_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A label for the rate. null clears it.", "title": "Display Name" }, "inclusive": { "description": "Whether prices charged in this country already include the tax (true) or have it added on top (false). Applies to prices whose tax_behavior is unspecified.", "title": "Inclusive", "type": "boolean" }, "rate_basis_points": { "description": "The rate in basis points: 2100 is 21 percent.", "maximum": 10000.0, "minimum": 0.0, "title": "Rate Basis Points", "type": "integer" } }, "title": "TaxRateUpdate", "type": "object" }, "TenantBillingProfileResponse": { "description": "Your own business identity, used for VAT decisions and printed on invoices.\n\n``country_code`` is what you have stored, or null if you never set it.\n``effective_country_code`` is the country the next charge will use: the\nstored value, or a platform default when you have none. ``vat_id`` is\nyour own VAT registration number and has no default. ``legal_name``, the\naddress fields and ``registration_number`` are printed on your invoices.", "properties": { "address_line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First line of your address on invoices, or null.", "title": "Address Line1" }, "address_line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second line of your address on invoices, or null.", "title": "Address Line2" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City of your address on invoices, or null.", "title": "City" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your business's country as stored, an ISO 3166-1 alpha-2 code, or null if never set.", "title": "Country Code" }, "effective_country_code": { "description": "The country the next charge uses for VAT: country_code, or the platform default when unset.", "title": "Effective Country Code", "type": "string" }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your business's registered legal name, printed on invoices, or null. BillKit's own invoices to you are issued to this name.", "title": "Legal Name" }, "object": { "const": "tenant_billing_profile", "default": "tenant_billing_profile", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal code of your address on invoices, or null.", "title": "Postal Code" }, "registration_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your company registration number, such as a chamber of commerce number, printed on invoices.", "title": "Registration Number" }, "tenant_id": { "description": "Id of your account, a UUID.", "title": "Tenant Id", "type": "string" }, "vat_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own VAT registration number, or null if not set.", "title": "Vat Id" } }, "required": [ "object", "tenant_id", "country_code", "effective_country_code", "vat_id", "address_line1", "address_line2", "postal_code", "city", "registration_number" ], "title": "TenantBillingProfileResponse", "type": "object" }, "TenantBillingProfileUpdate": { "additionalProperties": false, "description": "Your country, and optionally your VAT number and invoice address.\n\n``country_code`` is required on every call and cannot be cleared.\n``legal_name``, the address fields and ``registration_number`` are optional: omit one to\nleave it unchanged, or send ``null`` to clear it. ``vat_id`` can be set\nonce; changing or clearing a stored one returns ``vat_id_locked``.", "properties": { "address_line1": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "First line of your invoice address. Send null to clear it.", "title": "Address Line1" }, "address_line2": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Second line of your invoice address. Send null to clear it.", "title": "Address Line2" }, "city": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "City of your invoice address. Send null to clear it.", "title": "City" }, "country_code": { "description": "Your business's country, an ISO 3166-1 alpha-2 code such as NL. Upper-cased when stored.", "maxLength": 2, "minLength": 2, "title": "Country Code", "type": "string" }, "legal_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Your business's registered legal name, printed on invoices. Send null to clear it. BillKit does not issue its own invoice to you without it.", "title": "Legal Name" }, "postal_code": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "Postal code of your invoice address. Send null to clear it.", "title": "Postal Code" }, "registration_number": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Your company registration number, printed on invoices. Send null to clear it.", "title": "Registration Number" }, "vat_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Your VAT registration number. Can be set once: changing or clearing a stored one returns vat_id_locked. Omit to leave it unchanged.", "title": "Vat Id" } }, "required": [ "country_code" ], "title": "TenantBillingProfileUpdate", "type": "object" }, "TenantCapabilitiesResponse": { "description": "The payment methods and currencies your provider account can use, plus your allowed currencies.\n\n``enabled_methods`` and ``enabled_currencies`` come from a cached copy of\nyour provider account's settings, refreshed in the background.\n``provider_capabilities_refreshed_at`` is null and both lists are empty\nuntil the first refresh, which means \"not known yet\", not \"nothing\nenabled\". ``mollie_connected`` is true once any provider credential is\nstored.", "properties": { "allowed_currencies": { "description": "ISO 4217 codes, upper case, of the currencies your BillKit account accepts prices in.", "items": { "type": "string" }, "title": "Allowed Currencies", "type": "array" }, "enabled_currencies": { "description": "ISO 4217 codes of the currencies your provider account in this mode supports.", "items": { "type": "string" }, "title": "Enabled Currencies", "type": "array" }, "enabled_methods": { "description": "Payment methods enabled on your provider account in this mode, such as ideal or creditcard.", "items": { "type": "string" }, "title": "Enabled Methods", "type": "array" }, "livemode": { "description": "True if these are the live-mode capabilities, false for test mode.", "title": "Livemode", "type": "boolean" }, "mollie_connected": { "description": "True once any payment provider credential is stored for your account, in either mode.", "title": "Mollie Connected", "type": "boolean" }, "object": { "const": "tenant_capabilities", "default": "tenant_capabilities", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "provider_capabilities_refreshed_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the provider lists were last refreshed, in Unix seconds. Null until the first refresh.", "title": "Provider Capabilities Refreshed At" }, "provider_currencies_verified": { "description": "True once your provider account in this mode reports at least one currency that is also in allowed_currencies.", "title": "Provider Currencies Verified", "type": "boolean" }, "tenant_id": { "description": "Id of your account, a UUID.", "title": "Tenant Id", "type": "string" } }, "required": [ "object", "tenant_id", "livemode", "allowed_currencies", "provider_currencies_verified", "provider_capabilities_refreshed_at", "enabled_methods", "enabled_currencies", "mollie_connected" ], "title": "TenantCapabilitiesResponse", "type": "object" }, "TenantPortalBrandingResponse": { "description": "Your billing portal branding as configured, plus what customers see.\n\nThe configurable fields are null when never set. ``effective_business_name``\nand ``effective_support_email`` are the values the portal displays,\nfalling back to your account name, and to an empty string for the\nsupport address when you have not set one (the portal then shows no\ncontact line).", "properties": { "business_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The business name you set, or null if never set.", "title": "Business Name" }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/PortalTenantCapabilities" }, { "type": "null" } ], "description": "The portal and checkout feature flags you set, or null if never set." }, "effective_business_name": { "default": "", "description": "The name the portal displays: business_name, or your account name when unset.", "title": "Effective Business Name", "type": "string" }, "effective_support_email": { "default": "", "description": "The support address the portal displays: support_email, or the platform fallback when unset. An empty string means the portal shows no contact line.", "title": "Effective Support Email", "type": "string" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The logo URL you set, or null if never set.", "title": "Logo Url" }, "object": { "const": "tenant_portal_branding", "default": "tenant_portal_branding", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "support_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The support address you set, or null if never set.", "title": "Support Email" }, "theme": { "anyOf": [ { "$ref": "#/components/schemas/PortalTenantTheme-Output" }, { "type": "null" } ], "description": "The theme you set, or null if never set." } }, "required": [ "object", "business_name", "support_email", "logo_url", "theme", "capabilities", "effective_business_name", "effective_support_email" ], "title": "TenantPortalBrandingResponse", "type": "object" }, "TenantPortalBrandingUpdate": { "additionalProperties": false, "description": "Billing portal branding to change. Omitted fields are left alone; ``null`` clears one.\n\n``logo_url`` must use ``https`` and be at most 2048 characters.", "properties": { "business_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "The name the portal shows. Send null to fall back to your account name.", "title": "Business Name" }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/PortalTenantCapabilities" }, { "type": "null" } ], "description": "Which portal and embedded checkout features are on. Replaces the stored flags: a flag left out takes its default, and null restores every default." }, "logo_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "An https URL on the default port, at most 2048 characters, of the logo shown in the portal and on invoice PDFs. Send null to clear it.", "title": "Logo Url" }, "support_email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "description": "The contact address the portal shows. Send null to clear it.", "title": "Support Email" }, "theme": { "anyOf": [ { "$ref": "#/components/schemas/PortalTenantTheme-Input" }, { "type": "null" } ], "description": "The portal's colours and styling. Replaces the stored theme; null clears it." } }, "title": "TenantPortalBrandingUpdate", "type": "object" }, "TenantProviderCredentialResponse": { "description": "Confirms which provider key was replaced, and when. The key itself is never returned.", "properties": { "mode": { "description": "The mode whose provider key was replaced.", "title": "Mode", "type": "string", "x-extensible-enum": [ "live", "test" ] }, "object": { "const": "tenant_provider_credential", "default": "tenant_provider_credential", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "provider": { "const": "mollie", "description": "The payment provider whose key was replaced.", "title": "Provider", "type": "string" }, "rotated_at": { "description": "When the key was replaced, in Unix seconds.", "title": "Rotated At", "type": "integer" }, "tenant_id": { "description": "Id of your account, a UUID.", "title": "Tenant Id", "type": "string" } }, "required": [ "object", "tenant_id", "provider", "mode", "rotated_at" ], "title": "TenantProviderCredentialResponse", "type": "object" }, "TenantProviderCredentialRotateRequest": { "additionalProperties": false, "description": "A new payment provider API key to store for one mode.", "properties": { "api_key": { "description": "The new provider API key. Stored encrypted and never returned.", "maxLength": 128, "minLength": 8, "title": "Api Key", "type": "string" }, "mode": { "anyOf": [ { "enum": [ "live", "test" ], "type": "string" }, { "type": "null" } ], "description": "Which mode's provider key to replace. Must match the mode of the calling API key, or the request fails with mode_mismatch. Omit to use the calling key's mode.", "title": "Mode" }, "provider": { "const": "mollie", "default": "mollie", "description": "The payment provider. Only mollie.", "title": "Provider", "type": "string" } }, "required": [ "api_key" ], "title": "TenantProviderCredentialRotateRequest", "type": "object" }, "TestClockAdvance": { "additionalProperties": false, "properties": { "frozen_time": { "description": "The time to advance the clock to, in Unix seconds. Must be later than the clock's current frozen_time, and at most 4102444800 (2100-01-01).", "exclusiveMinimum": 0.0, "maximum": 4102444800.0, "title": "Frozen Time", "type": "integer" } }, "required": [ "frozen_time" ], "title": "TestClockAdvance", "type": "object" }, "TestClockCreate": { "additionalProperties": false, "properties": { "frozen_time": { "description": "The time the clock starts frozen at, in Unix seconds. At most 4102444800 (2100-01-01).", "exclusiveMinimum": 0.0, "maximum": 4102444800.0, "title": "Frozen Time", "type": "integer" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A label for the clock.", "title": "Name" } }, "required": [ "frozen_time" ], "title": "TestClockCreate", "type": "object" }, "TestClockResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "frozen_time": { "description": "The clock's current time, in Unix seconds. Attached customers are billed as of this time.", "title": "Frozen Time", "type": "integer" }, "id": { "description": "Unique identifier for the test clock, prefixed tc_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A label for the clock, or null.", "title": "Name" }, "object": { "const": "test_clock", "default": "test_clock", "description": "String representing the object's type.", "title": "Object", "type": "string" } }, "required": [ "id", "object", "created", "livemode", "name", "frozen_time" ], "title": "TestClockResponse", "type": "object" }, "UpcomingInvoice": { "description": "``invoice.upcoming``: a renewal BillKit will charge soon, before any invoice exists.\n\nThe amount and date are the ones frozen for the charge; anything that\nmoves the amount before the first attempt sends the event again.", "properties": { "amount_due_cents": { "description": "The gross amount the charge will collect, tax included, in minor units of currency.", "title": "Amount Due Cents", "type": "integer" }, "coupon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the coupon discounting this charge, or null if none.", "title": "Coupon Id" }, "currency": { "description": "ISO 4217 code of the charge's currency.", "title": "Currency", "type": "string" }, "customer_id": { "description": "Id of the subscription's customer.", "title": "Customer Id", "type": "string" }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the usage invoice the debit will collect, when a metered SEPA period closes. Null for a licensed renewal, which has no invoice until the charge settles.", "title": "Invoice Id" }, "next_payment_attempt": { "description": "When the charge will be attempted, in Unix seconds.", "title": "Next Payment Attempt", "type": "integer" }, "object": { "const": "upcoming_invoice", "default": "upcoming_invoice", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "period_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Start of the period this charge pays for, in Unix seconds, or null if not known.", "title": "Period Start" }, "price_id": { "description": "Id of the price being charged.", "title": "Price Id", "type": "string" }, "subscription_id": { "description": "Id of the subscription being renewed.", "title": "Subscription Id", "type": "string" }, "tax_cents": { "description": "The VAT included in amount_due_cents, in minor units of currency.", "title": "Tax Cents", "type": "integer" } }, "required": [ "object", "subscription_id", "customer_id", "invoice_id", "amount_due_cents", "currency", "tax_cents", "price_id", "coupon_id", "period_start", "next_payment_attempt" ], "title": "UpcomingInvoice", "type": "object" }, "UsageRecordCreate": { "additionalProperties": false, "properties": { "identifier": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Your deduplication key, unique within the subscription. Reporting an identifier again returns the first record unchanged instead of recording the usage twice.", "title": "Identifier" }, "metadata": { "anyOf": [ { "additionalProperties": { "maxLength": 500, "type": "string" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, { "type": "null" } ], "description": "Set of key-value pairs to store on the record.", "title": "Metadata" }, "occurred_at": { "anyOf": [ { "maximum": 253402300799.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "When the usage happened, in Unix seconds. Defaults to now. Must not predate the subscription or be more than five minutes in the future.", "title": "Occurred At" }, "quantity": { "description": "Units of usage to record, from 1 to 1000000.", "maximum": 1000000.0, "minimum": 1.0, "title": "Quantity", "type": "integer" } }, "required": [ "quantity" ], "title": "UsageRecordCreate", "type": "object" }, "UsageRecordResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "id": { "description": "Unique identifier for the usage record, prefixed ur_.", "title": "Id", "type": "string" }, "identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The deduplication key sent with the record. Null if none was.", "title": "Identifier" }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the invoice that billed this usage. Null until it is billed.", "title": "Invoice Id" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Set of key-value pairs stored on the record.", "title": "Metadata", "type": "object" }, "object": { "const": "usage_record", "default": "usage_record", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "occurred_at": { "description": "When the usage happened, in Unix seconds.", "title": "Occurred At", "type": "integer" }, "quantity": { "description": "Units of usage recorded.", "title": "Quantity", "type": "integer" }, "subscription_id": { "description": "Id of the metered subscription the usage was recorded against.", "title": "Subscription Id", "type": "string" }, "written_off_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When BillKit decided this usage will never be billed, because the subscription stopped billing before a period close picked it up, in Unix seconds. Null otherwise.", "title": "Written Off At" } }, "required": [ "id", "object", "created", "livemode", "subscription_id", "quantity", "occurred_at", "invoice_id", "identifier", "written_off_at", "metadata" ], "title": "UsageRecordResponse", "type": "object" }, "UsageSummaryResponse": { "description": "What the next period close will bill, and whether it will charge.", "properties": { "currency": { "description": "Three-letter ISO 4217 currency code of the price, uppercase.", "title": "Currency", "type": "string" }, "gross_cents": { "description": "What the close would charge, VAT included, in minor units of currency.", "title": "Gross Cents", "type": "integer" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "minimum_charge_cents": { "description": "The smallest amount the provider will charge, in minor units of currency.", "title": "Minimum Charge Cents", "type": "integer" }, "net_cents": { "description": "What the pending usage prices to before VAT, in minor units of currency.", "title": "Net Cents", "type": "integer" }, "object": { "const": "usage_summary", "default": "usage_summary", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "open_invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of an earlier invoiced cycle that is still unsettled. No charge for this period is attempted while one is open. Null if none is.", "title": "Open Invoice Id" }, "pending_quantity": { "description": "Units reported, not yet invoiced and not written off.", "title": "Pending Quantity", "type": "integer" }, "pending_record_count": { "description": "Number of usage records making up pending_quantity.", "title": "Pending Record Count", "type": "integer" }, "period_end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "End of the subscription's current period, when the next close bills, in Unix seconds. Null if it has none.", "title": "Period End" }, "period_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Start of the subscription's current period, in Unix seconds. Null if it has none.", "title": "Period Start" }, "subscription_id": { "description": "Id of the metered subscription summarized.", "title": "Subscription Id", "type": "string" }, "tax_cents": { "description": "VAT on that amount, in minor units of currency.", "title": "Tax Cents", "type": "integer" }, "will_charge": { "description": "Whether the next close would charge. False when there is no usage or gross_cents is under minimum_charge_cents; the usage then rolls into the next period and is not lost.", "title": "Will Charge", "type": "boolean" } }, "required": [ "object", "livemode", "subscription_id", "period_start", "period_end", "currency", "pending_quantity", "pending_record_count", "net_cents", "tax_cents", "gross_cents", "will_charge", "minimum_charge_cents", "open_invoice_id" ], "title": "UsageSummaryResponse", "type": "object" }, "WebhookDeliveryResponse": { "description": "One event's delivery to one webhook endpoint, with the result of the latest attempt.\n\n``status`` is ``pending`` while attempts continue, ``delivered`` once your\nreceiver returned a 2xx response, and ``failed`` when retries are\nexhausted or the endpoint was disabled.\n``last_response_body_excerpt`` holds at most the first 2048 characters of\nyour receiver's response.", "properties": { "attempt_count": { "description": "How many delivery attempts have been made, redeliveries included.", "title": "Attempt Count", "type": "integer" }, "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "delivered_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When your receiver accepted the event, in Unix seconds, or null if it has not.", "title": "Delivered At" }, "endpoint_id": { "description": "Id of the webhook endpoint it is delivered to.", "title": "Endpoint Id", "type": "string" }, "event_id": { "description": "Id of the event being delivered.", "title": "Event Id", "type": "string" }, "id": { "description": "Unique identifier for the delivery, beginning whd_.", "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the latest attempt failed without a response, such as a timeout or connection error, or why it was not sent. Null otherwise.", "title": "Last Error" }, "last_response_body_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first 2048 characters of your receiver's latest response body, or null if there was none.", "title": "Last Response Body Excerpt" }, "last_response_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status your receiver returned on the latest attempt, or null if it gave no response.", "title": "Last Response Code" }, "next_attempt_at": { "description": "When the next attempt is due, in Unix seconds. On a delivered or failed delivery, when the last attempt was scheduled.", "title": "Next Attempt At", "type": "integer" }, "object": { "const": "webhook_delivery", "default": "webhook_delivery", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "status": { "description": "pending while attempts continue, delivered after a 2xx response, failed once it gave up.", "title": "Status", "type": "string", "x-extensible-enum": [ "pending", "delivered", "failed" ] } }, "required": [ "id", "object", "event_id", "endpoint_id", "status", "attempt_count", "next_attempt_at", "last_response_code", "last_response_body_excerpt", "last_error", "created", "delivered_at" ], "title": "WebhookDeliveryResponse", "type": "object" }, "WebhookEndpointCreate": { "additionalProperties": false, "properties": { "description": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "An optional note about the endpoint.", "title": "Description" }, "enabled_events": { "description": "The event types to send to this endpoint, as listed by GET /v1/webhook_endpoints/event_types, or * for every event, including types added later. Defaults to [\"*\"].", "items": { "type": "string" }, "minItems": 1, "title": "Enabled Events", "type": "array" }, "url": { "description": "The URL BillKit sends events to: http or https, with a public host. Private and loopback addresses are refused.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookEndpointCreate", "type": "object" }, "WebhookEndpointCreatedEvent": { "description": "The body of a `webhook_endpoint.created` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "webhook_endpoint.created", "description": "What happened. Always `webhook_endpoint.created` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "WebhookEndpointCreatedEvent", "type": "object" }, "WebhookEndpointDeletedEvent": { "description": "The body of a `webhook_endpoint.deleted` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "webhook_endpoint.deleted", "description": "What happened. Always `webhook_endpoint.deleted` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "WebhookEndpointDeletedEvent", "type": "object" }, "WebhookEndpointResponse": { "properties": { "created": { "description": "Time at which the object was created, in Unix seconds.", "title": "Created", "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The note given to the endpoint, or null.", "title": "Description" }, "enabled_events": { "description": "The event types sent to this endpoint. * means every event.", "items": { "type": "string" }, "title": "Enabled Events", "type": "array" }, "id": { "description": "Unique identifier for the webhook endpoint, beginning we_.", "title": "Id", "type": "string" }, "livemode": { "description": "True if the object exists in live mode, false if it exists in test mode.", "title": "Livemode", "type": "boolean" }, "object": { "const": "webhook_endpoint", "default": "webhook_endpoint", "description": "String representing the object's type.", "title": "Object", "type": "string" }, "previous_secret_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fingerprint of the secret the last rotation replaced, or null if the secret was never rotated.", "title": "Previous Secret Fingerprint" }, "previous_secret_retired_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When the previous secret stops signing deliveries, in Unix seconds: 24 hours after the rotation. Until then each delivery is signed with both secrets. Null if never rotated.", "title": "Previous Secret Retired At" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The signing secret, beginning bkwhsec_. Present only in the responses that create the endpoint or rotate its secret; null everywhere else.", "title": "Secret" }, "secret_fingerprint": { "description": "First 12 hex characters of the SHA-256 of the current signing secret, to tell secrets apart without revealing them.", "title": "Secret Fingerprint", "type": "string" }, "status": { "description": "enabled if the endpoint receives events, disabled if it does not.", "title": "Status", "type": "string", "x-extensible-enum": [ "enabled", "disabled" ] }, "url": { "description": "The URL BillKit sends events to.", "title": "Url", "type": "string" } }, "required": [ "id", "object", "created", "livemode", "url", "enabled_events", "status", "description", "secret_fingerprint", "previous_secret_fingerprint", "previous_secret_retired_at", "secret" ], "title": "WebhookEndpointResponse", "type": "object" }, "WebhookEndpointUpdate": { "additionalProperties": false, "description": "The endpoint fields to change. Omitted fields are left alone.\n\n``description`` is cleared with ``null``. ``url``, ``enabled_events``\nand ``status`` cannot be cleared and refuse ``null`` with a 400.", "properties": { "description": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "An optional note about the endpoint. Send null to clear it.", "title": "Description" }, "enabled_events": { "description": "The event types to send to this endpoint, as listed by GET /v1/webhook_endpoints/event_types, or * for every event, including types added later. Replaces the stored list.", "items": { "type": "string" }, "minItems": 1, "title": "Enabled Events", "type": "array" }, "status": { "description": "disabled stops new events reaching the endpoint, and pending deliveries fail rather than being sent. enabled turns it back on.", "enum": [ "enabled", "disabled" ], "title": "Status", "type": "string" }, "url": { "description": "The URL BillKit sends events to: http or https, with a public host. Private and loopback addresses are refused.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" } }, "title": "WebhookEndpointUpdate", "type": "object" }, "WebhookEndpointUpdatedEvent": { "description": "The body of a `webhook_endpoint.updated` delivery.", "properties": { "created": { "description": "When the event was recorded, Unix seconds.", "type": "integer" }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponse", "description": "The object the event is about, as it stood when the event was recorded. At the top level: there is no `data.object` wrapper." }, "id": { "description": "The `evt_` id. Deduplicate on it.", "type": "string" }, "livemode": { "description": "True if the event happened in live mode, false if in test mode.", "type": "boolean" }, "object": { "const": "event", "description": "String representing the object's type. Always `event`.", "type": "string" }, "previous_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "On an update, the fields of `data` that changed, with their values before the change. Always present, and null when nothing changed." }, "type": { "const": "webhook_endpoint.updated", "description": "What happened. Always `webhook_endpoint.updated` on this delivery.", "type": "string" } }, "required": [ "id", "object", "type", "created", "livemode", "data", "previous_attributes" ], "title": "WebhookEndpointUpdatedEvent", "type": "object" } }, "securitySchemes": { "ApiKey": { "bearerFormat": "bk_live_... or bk_test_...", "description": "A secret API key. Its mode (live or test) is the mode of every object it reads or writes.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "BillKit", "url": "https://billkit.eu/" }, "description": "BillKit is a subscription billing API for EU businesses, with payments processed through Mollie. It covers customers, products, prices, checkout, subscriptions, payments, refunds, coupons, tax rates, invoices, credit notes and signed webhooks. Object IDs and Idempotency-Key behaviour follow Stripe's conventions. API keys start with bk_live_ or bk_test_, which secret scanners can recognise. This OpenAPI document is published under Apache-2.0 so you can generate and ship a client from it; the BillKit service itself is commercial and is not covered by that licence.", "license": { "identifier": "Apache-2.0", "name": "Apache License 2.0" }, "title": "BillKit", "version": "1.1.0" }, "openapi": "3.1.0", "paths": { "/v1/api_keys": { "get": { "description": "List your API keys, newest first.\n\nOnly keys in the same mode as the calling key are listed, so a test key\nnever sees live keys. Revoked keys are included, so check ``revoked_at``.\nThe keys themselves are never returned, only their prefixes.", "operationId": "list_api_keys", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_ApiKeyResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Api Keys", "tags": [ "api_keys" ], "x-required-scope": "api_keys:read" }, "post": { "description": "Issue a new API key.\n\nThe full key is returned once, in this response, and is never retrievable\nagain. Store it when you receive it. The new key is issued in the same\nmode as the key that created it, so a test key can only mint test keys.\n\n``scopes`` limits what the new key may do, so each integration can have a\nkey with only the access it needs. Omit it and the new key gets the\ncalling key's scopes. A key cannot grant scopes it does not hold itself,\nand an unknown scope returns 400.", "operationId": "create_api_key", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Api Key", "tags": [ "api_keys" ], "x-required-scope": "api_keys:write" } }, "/v1/api_keys/{api_key_id}": { "get": { "description": "Retrieve one API key's metadata.\n\nThe key itself is never returned; only its prefix, label, scopes and\nwhether it has been revoked. ``last_used_at`` is the useful field here,\nsince it tells you whether a key is still in service before you revoke\nit. A key belonging to another account returns 404, not 403.", "operationId": "get_api_key", "parameters": [ { "description": "Id of the API key, which starts ``ak_``.", "in": "path", "name": "api_key_id", "required": true, "schema": { "description": "Id of the API key, which starts ``ak_``.", "title": "Api Key Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Api Key", "tags": [ "api_keys" ], "x-required-scope": "api_keys:read" } }, "/v1/api_keys/{api_key_id}/revoke": { "post": { "description": "Revoke an API key so it stops working.\n\nDo this the moment a key might have leaked. It takes effect immediately\nand cannot be undone; issue a new key instead. Revoking an\nalready-revoked key returns it unchanged, so a retry is safe.\n\nA key is allowed to revoke itself, which is what you want if the leaked\nkey is the one you are calling with. Check ``last_used_at`` first if you\nare not sure what still depends on it.", "operationId": "revoke_api_key", "parameters": [ { "description": "Id of the API key, which starts ``ak_``.", "in": "path", "name": "api_key_id", "required": true, "schema": { "description": "Id of the API key, which starts ``ak_``.", "title": "Api Key Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Revoke Api Key", "tags": [ "api_keys" ], "x-required-scope": "api_keys:write" } }, "/v1/audit_logs": { "get": { "description": "List the record of who changed what in your account, newest first.\n\nEvery change made through the API or the console writes a row here,\nincluding which key or person made it and from what address. Reach for it\nwhen you need to answer \"who cancelled this subscription\" or to satisfy\nan auditor.\n\nNarrow with ``action`` (for example ``subscription.canceled``),\n``resource_type``, ``resource_id`` or ``actor_id``. All four match\nexactly. Audit rows are written once and cannot be edited or removed;\nthey are kept for 400 days and then deleted.\n\nChanges to the account as a whole (team members and invites, sign-in\nstep-ups, the custom domain, the business profile and portal branding,\nyour BillKit plan) are listed in both modes and carry\n``livemode: true``. Everything else is listed only in its own mode.", "operationId": "list_audit_logs", "parameters": [ { "description": "Only entries with exactly this action, such as subscription.canceled.", "in": "query", "name": "action", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only entries with exactly this action, such as subscription.canceled.", "title": "Action" } }, { "description": "Only entries about this type of object, such as subscription. Exact match.", "in": "query", "name": "resource_type", "required": false, "schema": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "Only entries about this type of object, such as subscription. Exact match.", "title": "Resource Type" } }, { "description": "Only entries about the object with this id. Exact match.", "in": "query", "name": "resource_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only entries about the object with this id. Exact match.", "title": "Resource Id" } }, { "description": "Only entries made by this actor: an API key's id (ak_...) or a console operator's id. Exact match.", "in": "query", "name": "actor_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only entries made by this actor: an API key's id (ak_...) or a console operator's id. Exact match.", "title": "Actor Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_AuditLogResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Audit Logs", "tags": [ "audit_logs" ], "x-required-scope": "audit_logs:read" } }, "/v1/audit_logs/{audit_log_id}": { "get": { "description": "Retrieve one audit entry, including the details recorded with it.\n\nAn entry belonging to another account returns 404, not 403.", "operationId": "get_audit_log", "parameters": [ { "description": "Id of the audit log entry, which starts ``al_``.", "in": "path", "name": "audit_log_id", "required": true, "schema": { "description": "Id of the audit log entry, which starts ``al_``.", "title": "Audit Log Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Audit Log", "tags": [ "audit_logs" ], "x-required-scope": "audit_logs:read" } }, "/v1/billing_portal/sessions": { "post": { "description": "Create a billing portal link for one subscription's customer.\n\nThe portal lets the customer update their payment method, change plan or\ncancel. Send them to the ``url`` in the response. The link is the\ncredential, since there is no customer login, so mint it on demand from a\npage where you have already authenticated the customer and never store or\nshare it.\n\nA session covers one subscription. The ``token`` is returned only in this\nresponse. By default a session expires two hours after it is created, or\nafter 30 minutes without use. Set ``deliver_email`` to also email the link\nto the customer's address on file; if they have none, no email is sent and\nthe call still succeeds. An unknown ``subscription_id`` returns 404.\n\nThis is the only way to a session that can change the plan, cancel,\nresume, apply a coupon or edit the customer's details. The links in\nBillKit's own customer emails open a session that can view billing and\npay, and nothing else.", "operationId": "create_portal_session", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalSessionCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalSessionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Portal Session", "tags": [ "billing_portal" ], "x-required-scope": "subscriptions:write" } }, "/v1/billing_portal/sessions/{session_id}/revoke": { "post": { "description": "Invalidate a portal session you minted that is already out in the world.\n\nUse it when a session URL has gone somewhere it should not have: pasted\ninto a ticket, or reported by a customer as phishing. It takes effect\nimmediately and cannot be undone; mint a fresh session if the customer\nstill needs access.\n\nIt covers the session this id names and nothing else. The portal links\nin BillKit's own emails (invoices, dunning, cancellation) are separate:\neach click on one opens a new session, so revoking a session does not\nclose them. Deleting or purging the customer revokes every link and\nsession they hold.\n\nRevoking an already-revoked session returns 200 and changes nothing, so a\nretry is safe. A session belonging to another account returns 404, not\n403.", "operationId": "revoke_portal_session", "parameters": [ { "description": "Id of the billing portal session, which starts ``bps_``.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Id of the billing portal session, which starts ``bps_``.", "title": "Session Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalSessionRevokeResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Revoke Portal Session", "tags": [ "billing_portal" ], "x-required-scope": "subscriptions:write" } }, "/v1/checkout/one_shot": { "get": { "description": "List one-off payments, newest first.\n\nThe one-off counterpart of ``GET /v1/payments``, which lists only\nsubscription payments. Filter by ``customer_id`` and by ``status``.\nFailed, expired and still-open payments are included, so check\n``status`` before counting a row as revenue. Refund totals are filled\nin as on retrieve.", "operationId": "list_one_shots", "parameters": [ { "description": "Only one-off payments for this customer.", "in": "query", "name": "customer_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only one-off payments for this customer.", "title": "Customer Id" } }, { "description": "Only one-off payments in this status. An unknown value is a 400.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "authorized", "canceled", "expired", "failed", "open", "paid", "pending", "refunded" ], "type": "string" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_OneShotPaymentResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List One Shots", "tags": [ "checkout" ], "x-required-scope": "checkout_sessions:read" }, "post": { "description": "Charge an existing customer once, with no subscription and no stored mandate.\n\nUse it for a one-off sale such as a top-up, a setup fee or a single order.\nSend the customer to ``redirect_url`` in the response to pay. No payment\nmethod is kept, so every further charge needs a new call.\n\nSet ``ui_mode`` to ``embedded`` to take the payment inside your own page\nwith the one-off payment element instead. Omit ``method``: the buyer picks\nit in the element. No payment is created yet; the response carries a\n``client_secret`` for the element and a null ``redirect_url``, and\n``expires_at`` is when the secret stops working, after which an unpaid\none-shot expires and ``one_shot_payment.failed`` fires. The amount, tax\nand events are the same as on the hosted flow. The ``client_secret`` is\nreturned by this call only.\n\nThe payment starts ``open`` and becomes ``paid`` when the provider\nconfirms it, which you learn from the ``one_shot_payment.succeeded``\nwebhook; ``one_shot_payment.failed`` covers the other outcome. ``currency``\nmust be one your account accepts and ``method`` one your provider account\nhas enabled for single payments in that currency, otherwise the call\nreturns 400. ``directdebit`` cannot be used here, and some methods have a\nprovider minimum that the charged amount must reach. ``tax_behavior``\ndecides whether ``amount_cents`` includes VAT or has it added on top. An\nunknown or deleted ``customer_id`` returns 404.", "operationId": "create_one_shot", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create One Shot", "tags": [ "checkout" ], "x-required-scope": "checkout_sessions:write" } }, "/v1/checkout/one_shot/{one_shot_id}": { "get": { "description": "Retrieve one one-off payment, including how much of it has been refunded.\n\n``amount_refunded_cents`` and ``amount_refundable_cents`` tell you what is\nleft to give back, which is what you need before calling\n``POST /v1/refunds``. Note that ``amount_refundable_cents`` ignores the\nrefund window, so a fully refundable balance can still be refused if the\nwindow has closed.\n\nA partial refund leaves the status ``paid`` with a balance remaining; only\na full refund flips it to ``refunded``. A payment belonging to another\naccount returns 404, not 403.", "operationId": "get_one_shot", "parameters": [ { "description": "Id of the one-shot payment, which starts ``osp_``.", "in": "path", "name": "one_shot_id", "required": true, "schema": { "description": "Id of the one-shot payment, which starts ``osp_``.", "title": "One Shot Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get One Shot", "tags": [ "checkout" ], "x-required-scope": "checkout_sessions:read" } }, "/v1/checkout/sessions": { "post": { "description": "Start a subscription sign-up for one price.\n\nThis is the only way to create a subscription. Send the customer to\n``url`` in the response; the subscription is created once their first\npayment succeeds, and does not appear in ``GET /v1/subscriptions`` before\nthen.\n\nIdentify the customer with exactly one of ``customer_id`` or\n``customer_email``. ``customer_email`` always creates a new customer,\nnever matches an existing one by address, and the customer is kept even\nif the payment later fails. The price and its product must both be\nactive: an archived price returns 404 and an archived product 400.\n\nSet ``ui_mode`` to ``embedded`` to collect payment inside your own page\nwith the checkout element. You get a ``client_secret`` instead of a\n``url``, and ``payment_method`` must be omitted because the buyer picks it in\nthe element. While a customer already has a first payment in progress,\na new hosted session for them returns 409 ``operation_pending``.\n\nSend ``country`` if you know where the buyer is. VAT on the first payment\nis worked out from the customer's country before the charge is created,\nand on the hosted flow the buyer is never asked for it before that. The\nembedded element asks the buyer itself. ``country`` is only stored when\nthe customer has none; it never overwrites an existing one.", "operationId": "create_checkout_session", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Checkout Session", "tags": [ "checkout" ], "x-required-scope": "checkout_sessions:write" } }, "/v1/checkout/sessions/{checkout_id}": { "get": { "description": "Retrieve one checkout session, to see whether the customer completed it.\n\nUseful on your success page, which the customer can reach before the\npayment provider has confirmed the payment. ``complete`` means the\nsign-up went through and ``subscription_id`` is set, and ``open`` means\nit has not resolved yet. A hosted session is ``expired`` once its\npayment fails or is abandoned. An embedded session stays ``open`` after\na failed or cancelled payment, so the buyer can retry, and is\n``expired`` only after ``expires_at``; list the customer's payments to\nsee how an attempt ended. Treat webhooks as the source of truth and this\nread as a way to render the right page immediately. A session belonging\nto another account returns 404.", "operationId": "get_checkout_session", "parameters": [ { "description": "Id of the Checkout session, which starts ``cs_``.", "in": "path", "name": "checkout_id", "required": true, "schema": { "description": "Id of the Checkout session, which starts ``cs_``.", "title": "Checkout Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Checkout Session", "tags": [ "checkout" ], "x-required-scope": "checkout_sessions:read" } }, "/v1/coupons": { "get": { "description": "List coupons, newest first.\n\nWithdrawn coupons are included, so check ``active`` before showing a\ncode as available.", "operationId": "list_coupons", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_CouponResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Coupons", "tags": [ "coupons" ], "x-required-scope": "coupons:read" }, "post": { "description": "Create a discount code customers can enter at checkout.\n\nSet either ``percent_off`` (more than 0 and at most 100, to two decimal places) or\n``amount_off_cents`` (a fixed amount), never both; ``discount_type`` is\noptional and follows from the one you set. Choose how long it lasts:\nonce, forever, or for a set number of months. You can limit it further\nwith a total redemption cap, an expiry date, a minimum order amount, and\na list of prices it applies to.\n\n``amount_off_cents`` and ``min_amount_cents`` are in minor units of\n``currency``, and the coupon applies only to prices in that currency.\n``currency`` is required with either when your account has more than one\ncurrency enabled; otherwise it defaults to the one you have.\n\nCodes are stored trimmed and upper-cased, so matching ignores case and\nsurrounding whitespace. Two coupons cannot share a code; a duplicate\nreturns 400. Pass the code as ``coupon_code`` to\n``POST /v1/checkout/sessions`` to apply it.", "operationId": "create_coupon", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Coupon", "tags": [ "coupons" ], "x-required-scope": "coupons:write" } }, "/v1/coupons/validate": { "post": { "description": "Check whether a code is usable, and what it would take off.\n\nCall this as the customer types a code, before they get as far as\ncheckout. It changes nothing and consumes no redemption, so it is safe to\ncall repeatedly.\n\nA code that is unknown, expired, exhausted or not applicable returns 200\nwith ``valid: false`` and a ``reason`` such as ``coupon_not_found``, not\nan error. Send ``price_id`` to check a price restriction, and\n``amount_cents`` to check a minimum amount and get ``discount_cents`` and\n``final_charge_cents`` back. A coupon in a different currency from the\nprice (or from ``currency``, when no price is sent) returns ``valid:\nfalse`` with ``coupon_currency_mismatch``.", "operationId": "validate_coupon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponValidateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponValidateResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Validate Coupon", "tags": [ "coupons" ], "x-required-scope": "coupons:read" } }, "/v1/coupons/{coupon_id}": { "get": { "description": "Retrieve one coupon, including how many times it has been redeemed.\n\nWithdrawn coupons are still returned, with ``active: false``, so a\ndiscount on a live subscription can be traced back to the coupon that\ngranted it. A coupon belonging to another account returns 404, not 403.", "operationId": "get_coupon", "parameters": [ { "description": "Id of the coupon, which starts ``coup_``.", "in": "path", "name": "coupon_id", "required": true, "schema": { "description": "Id of the coupon, which starts ``coup_``.", "title": "Coupon Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Coupon", "tags": [ "coupons" ], "x-required-scope": "coupons:read" }, "post": { "description": "Update a coupon's limits, or withdraw it.\n\nOnly the fields you send change. ``active: false`` withdraws the code: it\nstops being accepted at checkout, the coupon stays readable, and\ndiscounts already applied to subscriptions keep running. ``active: true``\nbrings it back. Coupons have no delete route; withdrawing is how you\nretire one. ``max_redemptions: null`` removes the redemption cap,\n``redeem_by: null`` the expiry, ``applies_to_price_ids: null`` the price\nrestriction and ``min_amount_cents: null`` the minimum. ``active``\ncannot be cleared: ``active: null`` returns 400.\n\nThe code, the discount and its duration cannot be changed, so a redeemed\ncoupon keeps meaning what it meant. Create a new coupon to offer a\ndifferent discount.", "operationId": "update_coupon", "parameters": [ { "description": "Id of the coupon, which starts ``coup_``.", "in": "path", "name": "coupon_id", "required": true, "schema": { "description": "Id of the coupon, which starts ``coup_``.", "title": "Coupon Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Coupon", "tags": [ "coupons" ], "x-required-scope": "coupons:write" } }, "/v1/credit_notes": { "get": { "description": "List credit notes, newest first.\n\nFilter by ``invoice_id`` to answer \"was this sale credited, and by how\nmuch\", which is the question when reconciling a single invoice. Filter by\n``customer_id`` for everything credited back to one customer.", "operationId": "list_credit_notes", "parameters": [ { "description": "Only credit notes issued against this invoice.", "in": "query", "name": "invoice_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only credit notes issued against this invoice.", "title": "Invoice Id" } }, { "description": "Only credit notes for this customer.", "in": "query", "name": "customer_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only credit notes for this customer.", "title": "Customer Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_CreditNoteResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Credit Notes", "tags": [ "credit_notes" ], "x-required-scope": "credit_notes:read" } }, "/v1/credit_notes/{credit_note_id}": { "get": { "description": "Retrieve one credit note.\n\nA credit note is the document that reverses part or all of an invoice.\nThey are issued for you when a refund settles, so there is no route to\nwrite one, and none is issued while a refund is still pending or if it\nfails. Refunds of subscription charges and of one-off sales both produce\none, because both are invoiced; a refund of a charge that was never\ninvoiced does not. A credit note belonging to another account returns\n404, not 403.", "operationId": "get_credit_note", "parameters": [ { "description": "Id of the credit note, which starts ``cn_``.", "in": "path", "name": "credit_note_id", "required": true, "schema": { "description": "Id of the credit note, which starts ``cn_``.", "title": "Credit Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Credit Note", "tags": [ "credit_notes" ], "x-required-scope": "credit_notes:read" } }, "/v1/credit_notes/{credit_note_id}/pdf": { "get": { "description": "Download the credit note as a PDF.\n\nThis is the document that evidences a refund for accounting purposes.\nAs with invoice PDFs, you will either receive the bytes directly or a\nredirect to a short-lived download link, so follow redirects. If PDF\nrendering is not available you get a 501 with code ``rendering_pending``;\nthe credit note itself is still available from\n``GET /v1/credit_notes/{id}``, so you can produce your own document.", "operationId": "get_credit_note_pdf", "parameters": [ { "description": "Id of the credit note, which starts ``cn_``.", "in": "path", "name": "credit_note_id", "required": true, "schema": { "description": "Id of the credit note, which starts ``cn_``.", "title": "Credit Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The feature is not available on this deployment.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Credit Note Pdf", "tags": [ "credit_notes" ], "x-required-scope": "credit_notes:read" } }, "/v1/customers": { "get": { "description": "List your customers, newest first.\n\nDeleted and purged customers are left out. There is no search by email\nor name, so keep your own mapping from your users to customer ids.\n``expand=stats`` adds each customer's live subscription count and\nlifetime net payments.\n\nA checkout started with ``customer_email`` creates the customer\nbefore the payment, so an abandoned checkout leaves a customer with\n``provisional: true``. Both kinds are returned by default. Pass\n``provisional=false`` for customers who have paid, or ``provisional=true``\nfor abandoned checkouts. Provisional customers are deleted after 30 days\nby default.", "operationId": "list_customers", "parameters": [ { "description": "Filter by whether the customer ever completed a payment. `false` returns real customers only; `true` returns abandoned checkouts (useful for cart-recovery email); omit to return both.", "in": "query", "name": "provisional", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by whether the customer ever completed a payment. `false` returns real customers only; `true` returns abandoned checkouts (useful for cart-recovery email); omit to return both.", "title": "Provisional" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_CustomerResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Customers", "tags": [ "customers" ], "x-required-scope": "customers:read" }, "post": { "description": "Create a customer.\n\nSubscriptions, one-off payments and portal sessions all belong to a\ncustomer. You can also pass ``customer_email`` to\n``POST /v1/checkout/sessions`` and have one created for you.\n\nCustomers are never deduplicated: two calls with the same email create\ntwo customers. Store the returned ``id`` against your own user record\nrather than looking customers up by email later, and send an\n``Idempotency-Key`` header so a retried request does not create a second\none. ``test_clock_id`` attaches the customer to a test clock (test mode only).", "operationId": "create_customer", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Customer", "tags": [ "customers" ], "x-required-scope": "customers:write" } }, "/v1/customers/{customer_id}": { "delete": { "description": "Delete a customer.\n\nAfterwards ``GET /v1/customers/{id}`` returns 404 and the customer is\nleft out of listings. This cannot be undone, and the response is a\ndeletion marker rather than the customer. A ``customer.deleted`` event\nis sent.\n\nPayments, invoices and refunds are kept and still readable. Personal data\nis not erased; use ``POST /v1/customers/{id}/purge`` for a GDPR erasure\nrequest.\n\nDeleting returns 409 ``state_conflict`` while the customer has a subscription that is\n``active``, ``trialing``, ``past_due`` or ``incomplete``, which includes a\npaused subscription and a trial that has not charged yet. Cancel the\nsubscription first; deleting never cancels anything for you.", "operationId": "delete_customer", "parameters": [ { "description": "Id of the customer, which starts ``cus_``.", "in": "path", "name": "customer_id", "required": true, "schema": { "description": "Id of the customer, which starts ``cus_``.", "title": "Customer Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete Customer", "tags": [ "customers" ], "x-required-scope": "customers:write" }, "get": { "description": "Retrieve one customer.\n\nDeleted and purged customers return 404, as does a customer belonging to\nanother account. Their payments and invoices remain readable.", "operationId": "get_customer", "parameters": [ { "description": "Id of the customer, which starts ``cus_``.", "in": "path", "name": "customer_id", "required": true, "schema": { "description": "Id of the customer, which starts ``cus_``.", "title": "Customer Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Customer", "tags": [ "customers" ], "x-required-scope": "customers:read" }, "post": { "description": "Update a customer's email, name, metadata or country.\n\nOnly the fields you send change. ``metadata`` replaces the whole object\nrather than merging into it, so send every key you want to keep, or\n``{}`` to empty it. ``name: null`` removes the name. ``email``,\n``country_code`` and ``metadata`` cannot be cleared: ``null`` on one of\nthem returns 400 naming the field.\n\n``country_code`` decides which VAT rate applies to the customer's next\ncharge; documents already issued are never repriced. Set a VAT\nregistration number with ``POST /v1/customers/{id}/vat_number``, which\nvalidates it. A deleted customer returns 404.", "operationId": "update_customer", "parameters": [ { "description": "Id of the customer, which starts ``cus_``.", "in": "path", "name": "customer_id", "required": true, "schema": { "description": "Id of the customer, which starts ``cus_``.", "title": "Customer Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Customer", "tags": [ "customers" ], "x-required-scope": "customers:write" } }, "/v1/customers/{customer_id}/purge": { "post": { "description": "Erase a customer's personal data and keep their financial history.\n\nUse this to act on a GDPR erasure request. The email is replaced with an\nunusable placeholder, and the name, metadata and VAT registration are\ncleared, including from the stored payloads of past events. The customer\nis marked deleted and returns 404 afterwards, so the response is a\ndeletion marker (``deleted: true``, ``purged: true``) rather than the\ncustomer, as on ``DELETE``. Payments, refunds, invoices\nand credit notes are kept, including the buyer details printed on issued\ndocuments, because those must be retained for accounting. A customer you\nhave already deleted can still be purged.\n\nPurging cannot be undone, so ``confirmed`` must be ``true`` or the call\nreturns 400. It returns 409 ``state_conflict`` while the customer has a subscription that is\n``active``, ``trialing``, ``past_due`` or ``incomplete`` (a paused\nsubscription is still ``active``), and 409 ``operation_pending`` while a\ncharge for them is in progress. Cancel and let payments settle first. A\n``customer.deleted`` event is sent with the details as they were before\nerasure, so your own systems can match the record.", "operationId": "purge_customer", "parameters": [ { "description": "Id of the customer, which starts ``cus_``.", "in": "path", "name": "customer_id", "required": true, "schema": { "description": "Id of the customer, which starts ``cus_``.", "title": "Customer Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPurgeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgedResource" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Purge Customer", "tags": [ "customers" ], "x-required-scope": "customers:write" } }, "/v1/customers/{customer_id}/vat_number": { "post": { "description": "Set or clear a business customer's VAT registration number.\n\nEvery number is checked against the EU VIES service. A valid number lets\nthe customer's next charge be zero rated under the EU reverse charge. A\nmalformed number, or one VIES rejects, returns 400 and the customer is\nunchanged; a number VIES rejects is still recorded in the audit log.\nIf VIES cannot confirm it (the service is down, the customer has no\ncountry, or the country is outside VIES, such as ``GB``), the number is\nstored with ``vat_number_validated: false`` and VAT is charged as normal.\n\nSend ``country_code`` with the number if the customer has no country\nyet. Send ``vat_number: null`` to clear the registration. Documents\nalready issued are never repriced.", "operationId": "set_customer_vat_number", "parameters": [ { "description": "Id of the customer, which starts ``cus_``.", "in": "path", "name": "customer_id", "required": true, "schema": { "description": "Id of the customer, which starts ``cus_``.", "title": "Customer Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVatNumberRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Set Customer Vat Number", "tags": [ "customers" ], "x-required-scope": "customers:write" } }, "/v1/disputes": { "get": { "description": "List chargebacks raised against your payments, newest first.\n\nA dispute is recorded when a payer's bank pulls funds back. You cannot\ncreate, contest or submit evidence for one through this API; they are\nhere so you can reconcile money that has left.\n\n``status`` is ``open`` (the funds were withdrawn) or ``won`` (they came\nback). There is no ``lost`` status because the payment provider sends no\nsignal for it, so a lost dispute stays ``open``. Filter with ``status``\n(comma-separated; an unknown value returns 400) or ``payment_id``, which\nmatches subscription payments only, not one-off payments.", "operationId": "list_disputes", "parameters": [ { "description": "Only disputes in these statuses, comma-separated. An unknown value is a 400.", "explode": false, "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "open", "won" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Only disputes against this subscription payment. One-off payments do not match.", "in": "query", "name": "payment_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only disputes against this subscription payment. One-off payments do not match.", "title": "Payment Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_DisputeResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Disputes", "tags": [ "disputes" ], "x-required-scope": "disputes:read" } }, "/v1/disputes/{dispute_id}": { "get": { "description": "Retrieve one chargeback.\n\nA dispute belonging to another account returns 404, not 403.", "operationId": "get_dispute", "parameters": [ { "description": "Id of the dispute, which starts ``dp_``.", "in": "path", "name": "dispute_id", "required": true, "schema": { "description": "Id of the dispute, which starts ``dp_``.", "title": "Dispute Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Dispute", "tags": [ "disputes" ], "x-required-scope": "disputes:read" } }, "/v1/events": { "get": { "description": "List the events recorded for your account, newest first.\n\nEvents record what happened, such as a customer created or a payment\nsucceeded, and are what your webhook endpoints receive. Check here when a\nwebhook did not arrive, to see whether the event happened at all.\n\n``type`` filters by exact event type, such as ``customer.created``, or\na comma-separated list of them (``type=invoice.paid,invoice.voided``);\nwildcards are not accepted, and an unknown type returns 400 rather than\nan empty list, as on ``GET /v1/events/stream``. ``expand=customer``\nattaches the customer an event refers to, where there is one.", "operationId": "list_events", "parameters": [ { "description": "Only events of these exact types, comma-separated, such as invoice.paid,invoice.voided. No wildcards. An unknown type is a 400.", "explode": false, "in": "query", "name": "type", "required": false, "schema": { "items": { "enum": [ "checkout.session.completed", "checkout.session.expired", "coupon.created", "coupon.updated", "credit_note.created", "customer.created", "customer.deleted", "customer.updated", "dispute.closed", "dispute.created", "dunning.email_required", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.payment_failed", "invoice.upcoming", "invoice.voided", "one_shot_payment.failed", "one_shot_payment.refunded", "one_shot_payment.succeeded", "payment.failed", "payment.succeeded", "price.archived", "price.created", "price.updated", "product.archived", "product.created", "product.updated", "refund.created", "refund.failed", "refund.succeeded", "subscription.canceled", "subscription.coupon_applied", "subscription.coupon_expired", "subscription.created", "subscription.past_due", "subscription.paused", "subscription.payment_method_updated", "subscription.plan_changed", "subscription.reactivated", "subscription.resumed", "subscription.trial_ended", "subscription.trial_started", "subscription.trial_will_end", "subscription.updated", "webhook_endpoint.created", "webhook_endpoint.deleted", "webhook_endpoint.updated" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_EventResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Events", "tags": [ "events" ], "x-required-scope": "events:read" } }, "/v1/events/stream": { "get": { "description": "Receive this account's events as they happen, over Server-Sent Events.\n\nEach event arrives as a ``message`` frame whose ``id:`` is the event id\nand whose data is exactly the body a webhook delivery of that event\ncarries, ``previous_attributes`` included (``null`` when nothing changed). Use\nit to react in near real time, for example to forward events to a local\nwebhook receiver during development: the receiver sees the payload it\nwill see in production.\n\nThe stream starts from the moment you connect. To resume without gaps,\npass the last event id you processed as ``starting_after``: every later\nevent is sent in order before the stream goes live. Any of your event ids\nworks, including one from ``GET /v1/events`` or a webhook. An event\nrecorded at the same moment as the one you resume from can be sent\nagain, so de-duplicate by event id as you would for webhooks. A browser\n``EventSource`` sends the ``Last-Event-ID`` header on reconnect, which is\nused when ``starting_after`` is absent. An id that is not one of your\nevents returns 400.\n\nEvents arrive in the order they were recorded. An event is held back\nwhile an earlier write is still being committed; if that takes more than\nabout 30 seconds, later events are sent ahead of it and it follows when\nit completes.\n\n``type`` is an optional event type, or a comma-separated list of them,\nas on ``GET /v1/events``. Unknown types return 400 naming them, so a typo\ncannot leave you with a stream that stays silent. The server closes the connection with a\n``timeout`` frame after about an hour, or sooner if it has fallen far\nbehind, and sends an ``unauthorized`` frame and closes if the API key is\nrevoked; reconnect with the last id you saw. Nothing is retried, so use\nwebhook endpoints for delivery you depend on.", "operationId": "stream_events", "parameters": [ { "description": "Only events of these exact types, comma-separated, such as invoice.paid,invoice.voided. No wildcards. An unknown type is a 400.", "explode": false, "in": "query", "name": "type", "required": false, "schema": { "items": { "enum": [ "checkout.session.completed", "checkout.session.expired", "coupon.created", "coupon.updated", "credit_note.created", "customer.created", "customer.deleted", "customer.updated", "dispute.closed", "dispute.created", "dunning.email_required", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.payment_failed", "invoice.upcoming", "invoice.voided", "one_shot_payment.failed", "one_shot_payment.refunded", "one_shot_payment.succeeded", "payment.failed", "payment.succeeded", "price.archived", "price.created", "price.updated", "product.archived", "product.created", "product.updated", "refund.created", "refund.failed", "refund.succeeded", "subscription.canceled", "subscription.coupon_applied", "subscription.coupon_expired", "subscription.created", "subscription.past_due", "subscription.paused", "subscription.payment_method_updated", "subscription.plan_changed", "subscription.reactivated", "subscription.resumed", "subscription.trial_ended", "subscription.trial_started", "subscription.trial_will_end", "subscription.updated", "webhook_endpoint.created", "webhook_endpoint.deleted", "webhook_endpoint.updated" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Resume after this event id instead of starting from now. The stream replays every event recorded after it, in order, then continues live. Any of your event ids works, from this stream, GET /v1/events or a webhook. Unknown ids are rejected with a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Resume after this event id instead of starting from now. The stream replays every event recorded after it, in order, then continues live. Any of your event ids works, from this stream, GET /v1/events or a webhook. Unknown ids are rejected with a 400.", "title": "Starting After" } }, { "description": "Standard SSE resume header, sent automatically by a browser EventSource on reconnect. Used only when starting_after is absent.", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Standard SSE resume header, sent automatically by a browser EventSource on reconnect. Used only when starting_after is absent.", "title": "Last-Event-Id" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "A server-sent event stream; see the operation description.", "type": "string" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Stream Events", "tags": [ "events" ], "x-required-scope": "events:read" } }, "/v1/events/{event_id}": { "get": { "description": "Retrieve one event, including its full ``data`` payload.\n\nUse it to re-read what a webhook delivery contained. The payload is a\nsnapshot of the object when the event happened, not its current state.\nPurging a customer redacts their personal data from past events. An\nevent belonging to another account returns 404.", "operationId": "get_event", "parameters": [ { "description": "Id of the event, which starts ``evt_``.", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Id of the event, which starts ``evt_``.", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Event", "tags": [ "events" ], "x-required-scope": "events:read" } }, "/v1/invoices": { "get": { "description": "List invoices, newest first, without their line items.\n\nFilter by ``customer_id``, ``subscription_id`` or ``payment_id``, and by\n``status``: one of ``open``, ``paid``, ``void`` or ``uncollectible``\n(any other value returns 400). ``expand=customer``\nattaches each invoice's customer. Retrieve a single invoice to get its\nline items.", "operationId": "list_invoices", "parameters": [ { "description": "Only invoices for this customer.", "in": "query", "name": "customer_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only invoices for this customer.", "title": "Customer Id" } }, { "description": "Only invoices issued for this subscription.", "in": "query", "name": "subscription_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only invoices issued for this subscription.", "title": "Subscription Id" } }, { "description": "Only invoices issued for this payment.", "in": "query", "name": "payment_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only invoices issued for this payment.", "title": "Payment Id" } }, { "description": "Only invoices in this status. An unknown value is a 400.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "open", "paid", "uncollectible", "void" ], "type": "string" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_InvoiceResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Invoices", "tags": [ "invoices" ], "x-required-scope": "invoices:read" } }, "/v1/invoices/{invoice_id}": { "get": { "description": "Retrieve one invoice, with its line items.\n\nLine items are only returned here, not on the list. Tax figures and the\nbuyer's name, email, address and VAT number are recorded when the\ninvoice is issued and do not follow later changes to the customer.\n``expand=customer`` attaches the customer. An invoice belonging to\nanother account returns 404.", "operationId": "get_invoice", "parameters": [ { "description": "Id of the invoice, which starts ``inv_``.", "in": "path", "name": "invoice_id", "required": true, "schema": { "description": "Id of the invoice, which starts ``inv_``.", "title": "Invoice Id", "type": "string" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Invoice", "tags": [ "invoices" ], "x-required-scope": "invoices:read" } }, "/v1/invoices/{invoice_id}/email": { "post": { "description": "Email the invoice to the customer again.\n\nThe email follows the invoice's status. A paid invoice gets the same\nbranded receipt as when it was issued. An open invoice gets a request\nfor payment: the amount due, the due date, and a link to pay with a\ndifferent payment method when the invoice belongs to a subscription.\nAn uncollectible invoice gets a notice that it is unpaid. Every\nversion carries new links, because the original ones may have expired.\n\nA void invoice is owed by nobody, so there is nothing to send: it\nreturns 409 ``state_conflict``, and so does an invoice whose customer\nhas been purged: the invoice is kept as an accounting record, but the\naddress on it is no longer used to contact them. The email goes to the email address\nrecorded on the invoice, not the customer's current one, and\n``recipient`` in the response says which address that was. An invoice\nwith no email address returns 400.\n\nSending is best effort: a 200 means the email was queued, not that it\nwas delivered.", "operationId": "email_invoice", "parameters": [ { "description": "Id of the invoice, which starts ``inv_``.", "in": "path", "name": "invoice_id", "required": true, "schema": { "description": "Id of the invoice, which starts ``inv_``.", "title": "Invoice Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEmailResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Email Invoice", "tags": [ "invoices" ], "x-required-scope": "invoices:write" } }, "/v1/invoices/{invoice_id}/pdf": { "get": { "description": "Download the invoice as a PDF.\n\nThe PDF is rendered on the first request and stored, so later requests\nare faster. The response is either the PDF itself or a redirect to a\nshort-lived download link, so follow redirects. If PDF rendering is not\navailable on this deployment you get a 501 with code\n``rendering_pending``; the invoice itself is still available from\n``GET /v1/invoices/{id}``, so you can produce your own document.", "operationId": "get_invoice_pdf", "parameters": [ { "description": "Id of the invoice, which starts ``inv_``.", "in": "path", "name": "invoice_id", "required": true, "schema": { "description": "Id of the invoice, which starts ``inv_``.", "title": "Invoice Id", "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The feature is not available on this deployment.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Invoice Pdf", "tags": [ "invoices" ], "x-required-scope": "invoices:read" } }, "/v1/invoices/{invoice_id}/void": { "post": { "description": "Void an invoice that should not have been issued.\n\nUse it for an amount that was never owed, such as a period metered wrong\nor a customer billed by mistake. The invoice keeps its number and stays\nreadable, stops being collectable, and ``invoice.voided`` is sent. Usage\nbilled on it is not billed again later. ``reason`` is optional and is\nrecorded in the audit log.\n\nA paid invoice cannot be voided and returns 409\n``invoice_not_voidable``: refund the payment instead, and the refund\nissues a credit note when it succeeds. While a charge against the\ninvoice is still in progress the call returns 409 ``operation_pending``.\nVoiding an invoice that is already void returns it unchanged and sends no\nsecond event.", "operationId": "void_invoice_route", "parameters": [ { "description": "Id of the invoice, which starts ``inv_``.", "in": "path", "name": "invoice_id", "required": true, "schema": { "description": "Id of the invoice, which starts ``inv_``.", "title": "Invoice Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceVoid" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Void Invoice", "tags": [ "invoices" ], "x-required-scope": "invoices:write" } }, "/v1/payments": { "get": { "description": "List subscription payments, newest first.\n\nFailed and pending payments are included, so check ``status`` before\ncounting a row as revenue. Filter by ``customer_id``; ``expand=customer``\nand ``expand=subscription`` attach those objects. One-off payments are\nnot listed here.\n\nPayment-method verification charges, made when a customer authorises a\nnew payment method, are left out because nothing was sold. They can\nstill be retrieved by id.", "operationId": "list_payments", "parameters": [ { "description": "Only payments by this customer.", "in": "query", "name": "customer_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only payments by this customer.", "title": "Customer Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer, subscription. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer, subscription. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_PaymentResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Payments", "tags": [ "payments" ], "x-required-scope": "payments:read" } }, "/v1/payments/{payment_id}": { "get": { "description": "Retrieve one subscription payment, including how much has been refunded.\n\nCovers every charge tied to a subscription: the first payment, renewals,\nplan changes, payment-method verifications and metered periods. One-off\npayments are retrieved with ``GET /v1/checkout/one_shot/{id}``.\n\n``amount_refunded_cents`` includes pending as well as succeeded refunds,\nso it matches what ``POST /v1/refunds`` will still allow.\n``expand=customer`` and ``expand=subscription`` attach those objects.\n\n``expand=refund_eligibility`` says whether ``POST /v1/refunds`` for the\nremaining balance would succeed now, applying the refund window and the\nprice's refund policy, which ``amount_refundable_cents`` does not. When\nit would not, ``reason`` is ``not_paid``, ``unrefundable_type``,\n``window_expired``, ``fully_refunded``, ``disputed`` (an open dispute\ntook what was left), ``operation_pending`` (another refund is still\nbeing confirmed) or ``plan_change_pending`` (a plan change is still\nsettling and a refund of the whole balance would end the subscription;\na partial refund is allowed meanwhile, so ``amount_cents`` stays set).\nTreat an unknown reason as \"not refundable\". The answer is advisory:\n``POST /v1/refunds`` makes the final decision under a lock.\n\nA payment belonging to another account returns 404.", "operationId": "get_payment", "parameters": [ { "description": "Id of the payment, which starts ``pay_``.", "in": "path", "name": "payment_id", "required": true, "schema": { "description": "Id of the payment, which starts ``pay_``.", "title": "Payment Id", "type": "string" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer, refund_eligibility, subscription. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer, refund_eligibility, subscription. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Payment", "tags": [ "payments" ], "x-required-scope": "payments:read" } }, "/v1/payments/{payment_id}/provider": { "get": { "description": "Fetch the payment provider's own record of this payment, live.\n\nUse it for support questions BillKit's payment object does not answer,\nsuch as the card BIN, the iDEAL bank or the provider's own status. The\nrecord is read from the provider on every request and returned verbatim\nin ``payload``; its shape is the provider's and can change without\nnotice, so treat it as diagnostic data.\n\nIf the provider cannot be reached or does not return the payment, the\nresponse is still 200, with ``available: false`` and an\n``unavailable_reason``. A payment belonging to another account returns\n404.\n\nFor a customer who has been purged the payload is redacted and\n``redacted`` is ``true``: amounts, statuses, timestamps and identifiers\nstay, and the account holder, bank and card details, description and\nmetadata are removed. Mollie keeps the payment itself under its own\nretention obligations, so without this the live read would hand back\npersonal data BillKit has erased.", "operationId": "get_payment_provider_payload", "parameters": [ { "description": "Id of the payment, which starts ``pay_``.", "in": "path", "name": "payment_id", "required": true, "schema": { "description": "Id of the payment, which starts ``pay_``.", "title": "Payment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPayloadResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Payment Provider Payload", "tags": [ "payments" ], "x-required-scope": "payments:read" } }, "/v1/ping": { "get": { "description": "Check that a key works, and see which account and mode it resolves to.\n\nReturns ``tenant_id``, ``mode`` (``test`` or ``live``) and ``object``.\nNothing is written and nothing is charged.\n\nThe one route that requires no scope, so a key narrowed to a single\nresource answers here as readily as a full-access one. ``mode`` comes\nfrom the key's own prefix, which makes this the cheapest way to\nconfirm which set of data a deployment is pointed at.", "operationId": "ping", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Ping", "tags": [ "meta" ] } }, "/v1/prices": { "get": { "description": "List your prices, newest first.\n\nArchived prices are included, so check ``active``. Pass ``product_id``\nto list one product's prices.", "operationId": "list_prices", "parameters": [ { "description": "Only prices of this product.", "in": "query", "name": "product_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only prices of this product.", "title": "Product Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_PriceResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Prices", "tags": [ "prices" ], "x-required-scope": "prices:read" }, "post": { "description": "Create a price for a product: the amount, currency and interval a customer buys.\n\nA price also carries the trial length, the payment methods accepted at\ncheckout, the refund policy, and ``tax_behavior``, which says whether\nthe amount includes VAT or has it added on top. The product must exist\nand be active. Amount, currency and interval cannot be changed later; to\ncharge something different, create a new price and archive the old one\nwith ``POST /v1/prices/{id}``. Customers already on it keep renewing.\n\nA licensed price sends ``amount_cents`` in whole minor units, charged\nevery period. A metered price (``usage_type: \"metered\"``) must use\n``interval: \"month\"``, has no trial and cannot refund on cancellation.\nIt sends either ``amount_cents`` or ``unit_amount_decimal``, a per-unit\nrate in minor units with up to 12 decimal places, as a string:\n``\"0.02\"`` is 0.02 cents per unit. Keep it a string in your code, since\na floating-point number cannot hold it exactly. The period's total\nquantity is multiplied by the rate and rounded once, on the invoice.\n\nA metered price can instead be priced in bands with\n``billing_scheme: \"tiered\"``, ``tiers`` and ``tiers_mode``, and then\nsends no amount. ``graduated`` prices the units that fall inside each\nband; ``volume`` uses the total quantity to pick one band, which then\nprices every unit. The last band must be open-ended (``up_to: \"inf\"``).\nBreaking any of these rules returns 400.", "operationId": "create_price", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Price", "tags": [ "prices" ], "x-required-scope": "prices:write" } }, "/v1/prices/{price_id}": { "get": { "description": "Retrieve one price, including its trial, tax and refund-window settings.\n\nA price belonging to another account returns 404, not 403.", "operationId": "get_price", "parameters": [ { "description": "Id of the price, which starts ``price_``.", "in": "path", "name": "price_id", "required": true, "schema": { "description": "Id of the price, which starts ``price_``.", "title": "Price Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Price", "tags": [ "prices" ], "x-required-scope": "prices:read" }, "post": { "description": "Archive a price, restore it, or change its forward-looking settings.\n\nSend ``active: false`` to stop selling a price. It keeps its id and stays\nreadable, and customers already on it keep renewing at it, but new\ncheckouts against it are refused and it is not offered as a plan change.\n``active: true`` puts it back on sale; if its product is archived,\nrestore the product too.\n\nYou can also change ``metadata``, ``payment_methods`` and the refund\npolicy (``refund_on_cancel``, ``refund_window_initial_days``,\n``refund_window_renewal_days``). The refund settings are read when a\ncancellation or refund happens, so they apply to customers already on\nthe price. Send a refund window as ``null`` to go back to the default,\nand ``payment_methods`` as ``null`` to have the price follow your\naccount's payment methods again.\n``tax_behavior`` can be set once, while it is ``unspecified``, and not\nchanged after that. Amount, currency, interval and usage type cannot be\nchanged.\n\nOnly the fields you send change. ``metadata`` replaces the whole object;\nsend ``{}`` to empty it. Only the two refund windows and\n``payment_methods`` accept ``null``:\n``null`` on any other field returns 400 naming the field, because none\nof them can be cleared. A request that changes nothing returns\nthe price and sends no event. Archiving sends ``price.archived``; any\nother change sends ``price.updated``.", "operationId": "update_price", "parameters": [ { "description": "Id of the price, which starts ``price_``.", "in": "path", "name": "price_id", "required": true, "schema": { "description": "Id of the price, which starts ``price_``.", "title": "Price Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Price", "tags": [ "prices" ], "x-required-scope": "prices:write" } }, "/v1/products": { "get": { "description": "List your products, newest first.\n\nArchived products are included, so check ``active`` before showing one\non a pricing page. ``expand=prices`` attaches each product's prices,\nactive ones first and archived ones included. ``expand=stats`` attaches\nthe current subscriber count and monthly recurring revenue.\n``expand=default_price`` attaches the default price as ``default_price``.", "operationId": "list_products", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: default_price, prices, stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: default_price, prices, stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_ProductResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Products", "tags": [ "products" ], "x-required-scope": "products:read" }, "post": { "description": "Create a product: the name and description of something you sell.\n\nA product has no amount of its own. Add one or more prices to it with\n``POST /v1/prices``, for example monthly and yearly, or one per\ncurrency. The first price you create becomes the product's\n``default_price_id``. ``allow_promotion_codes`` lets buyers type a coupon code at\ncheckout for this product; it is off by default.", "operationId": "create_product", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Product", "tags": [ "products" ], "x-required-scope": "products:write" } }, "/v1/products/{product_id}": { "get": { "description": "Retrieve one product.\n\nArchived products are still returned, with ``active: false``.\n``expand=prices``, ``expand=stats`` and ``expand=default_price`` work\nas on the list. A product\nbelonging to another account returns 404.", "operationId": "get_product", "parameters": [ { "description": "Id of the product, which starts ``prod_``.", "in": "path", "name": "product_id", "required": true, "schema": { "description": "Id of the product, which starts ``prod_``.", "title": "Product Id", "type": "string" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: default_price, prices, stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: default_price, prices, stats. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Product", "tags": [ "products" ], "x-required-scope": "products:read" }, "post": { "description": "Update a product's details, or archive it.\n\nOnly the fields you send change; ``metadata`` and ``marketing_features``\nare replaced rather than merged.\n\n``active: false`` archives the product. New checkouts for any of its\nprices are refused, it is not offered as a plan change in the billing\nportal, and no new prices can be created under it. Existing subscribers\nkeep renewing, and the product stays readable with ``active: false``.\nArchiving sends ``product.archived`` instead of ``product.updated``.\nIts prices keep their own ``active`` value; archive them separately with\n``POST /v1/prices/{id}`` if you want that. ``active: true`` restores the\nproduct.\n\n``description: null`` removes the description and\n``marketing_features: null`` the feature list; send ``metadata: {}`` to\nempty the metadata. ``name``, ``metadata``, ``active`` and\n``allow_promotion_codes`` cannot be cleared: ``null`` on one of them\nreturns 400 naming the field.\n\n``default_price_id`` picks the price the billing portal offers on that\nprice's interval. It must be an active price of this product; ``null``\nclears it. Archiving the default price releases it: the product then has\nno default, and the portal offers the newest active price on that\ninterval until another default is set.", "operationId": "update_product", "parameters": [ { "description": "Id of the product, which starts ``prod_``.", "in": "path", "name": "product_id", "required": true, "schema": { "description": "Id of the product, which starts ``prod_``.", "title": "Product Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Product", "tags": [ "products" ], "x-required-scope": "products:write" } }, "/v1/refunds": { "get": { "description": "List refunds, newest first.\n\nCovers refunds against subscription payments and against one-off\npayments alike. There are no filters here, so to find the refunds on a\nparticular charge read ``amount_refunded_cents`` on the payment itself.", "operationId": "list_refunds", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_RefundResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Refunds", "tags": [ "refunds" ], "x-required-scope": "refunds:read" }, "post": { "description": "Refund a payment, in full or in part.\n\nName one target: ``payment_id`` for a subscription payment,\n``one_shot_payment_id`` for a one-off payment, or ``subscription_id``\nfor that subscription's most recent payment. Omit ``amount_cents`` to\nrefund everything still refundable, or send it to refund less. Several\npartial refunds are allowed up to the amount paid.\n\nOnly ``paid`` first, renewal and metered-period payments can be refunded;\nany other payment, or one outside its refund window (set on the price, or\non the one-off payment), returns 409 ``state_conflict``. An amount above\nwhat is left returns 400.\nMoney already taken back by an open chargeback is not refundable.\n\nThree 409s are settled facts rather than contention, so retrying does\nnot help: ``charge_already_refunded`` when earlier refunds (pending\nincluded) cover the whole charge, ``charge_disputed`` when an open\nchargeback has taken back the rest, and ``refund_duplicate`` when a\nrequest without an ``Idempotency-Key`` repeats an earlier one (same\ncharge, same amount) and the provider returned that earlier refund.\nSend a distinct ``Idempotency-Key`` to make a deliberate second refund\nof the same amount.\n\nRefunding a subscription's payment in full cancels the subscription\nimmediately. A partial refund leaves it running, and a full refund of a\nmetered period never cancels.\n\nA refund is usually ``pending`` when this returns and becomes\n``succeeded`` or ``failed`` later, so handle the ``refund.failed`` event\nrather than treating a 200 as money returned.\n\nA ``402`` with ``payment_refused`` means the payment provider refused\nthe refund and created nothing; retrying will not change that. A\n``502`` means the provider could not confirm whether it created the\nrefund. Retry with the same ``Idempotency-Key``: an unconfirmed\nrefund keeps its amount reserved, and the retry finishes that refund\ninstead of starting another.", "operationId": "create_refund", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Refund", "tags": [ "refunds" ], "x-required-scope": "refunds:write" } }, "/v1/refunds/{refund_id}": { "get": { "description": "Retrieve one refund and check whether it has settled.\n\n``status`` is ``pending``, ``succeeded`` or ``failed``, whatever the\npayment provider's own status. A refund belonging to another account\nreturns 404.", "operationId": "get_refund", "parameters": [ { "description": "Id of the refund, which starts ``re_``.", "in": "path", "name": "refund_id", "required": true, "schema": { "description": "Id of the refund, which starts ``re_``.", "title": "Refund Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Refund", "tags": [ "refunds" ], "x-required-scope": "refunds:read" } }, "/v1/subscriptions": { "get": { "description": "List subscriptions, newest first.\n\nA subscription is created when a customer completes a checkout and the\nfirst payment succeeds, so a checkout session that is still open has no\nsubscription here yet.\n\nFilter by ``customer_id``, ``status`` and ``renewal_state``; the last two\ntake comma-separated lists such as ``status=active,past_due``, and an\nunknown value returns 400 listing the valid ones. ``status`` is where the\nsubscription stands with its payments: ``incomplete``, ``trialing``,\n``active``, ``past_due`` or ``canceled``. ``renewal_state`` is what\nhappens at the end of the current period: ``auto_renew``, ``paused``,\n``canceling`` or ``stopped``. A paused subscription keeps\n``status: active``, so filter with ``renewal_state=paused`` to find it.\n``expand`` accepts ``customer``, ``price`` (which also returns\n``mrr_cents``) and ``refund_eligibility``.", "operationId": "list_subscriptions", "parameters": [ { "description": "Only subscriptions of this customer.", "in": "query", "name": "customer_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Only subscriptions of this customer.", "title": "Customer Id" } }, { "description": "Only subscriptions in these statuses, comma-separated. An unknown value is a 400. A paused subscription is active: filter it with renewal_state.", "explode": false, "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "active", "canceled", "incomplete", "past_due", "trialing" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Only subscriptions in these renewal states, comma-separated. An unknown value is a 400.", "explode": false, "in": "query", "name": "renewal_state", "required": false, "schema": { "items": { "enum": [ "auto_renew", "canceling", "paused", "stopped" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer, price, refund_eligibility. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer, price, refund_eligibility. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_SubscriptionResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Subscriptions", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:read" } }, "/v1/subscriptions/{subscription_id}": { "get": { "description": "Retrieve one subscription.\n\nTo decide whether to give the customer access, read ``serves_customer``.\n``status`` alone is not enough: a cancelled or paused subscription keeps\n``status: active`` with ``renewal_state`` set to ``canceling`` or\n``paused`` until shortly after ``current_period_end``, when a background\njob closes it, but access should end at ``current_period_end``, which\n``serves_customer`` accounts for.\n\n``next_charge_amount_cents`` is what the next renewal will charge, after any\nrecurring coupon and with VAT added on a tax-exclusive price, and is null\nwhen the subscription will not renew or its price is metered. ``expand``\naccepts ``customer``, ``price`` (which also returns ``mrr_cents``) and\n``refund_eligibility``. A subscription belonging to another account\nreturns 404.", "operationId": "get_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "Comma-separated related objects to include in the response. Expandable here: customer, price, refund_eligibility. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Comma-separated related objects to include in the response. Expandable here: customer, price, refund_eligibility. An unknown name is a 400, and embedding another resource needs that resource's read scope.", "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:read" } }, "/v1/subscriptions/{subscription_id}/cancel": { "post": { "description": "Stop a subscription renewing at the end of the current period.\n\nThe response has ``cancel_at_period_end: true``, ``renewal_state:\n\"canceling\"`` and still ``status: active``, because the current period is\npaid for. The customer should keep access until ``current_period_end``;\n``serves_customer`` turns false at that point, so use it rather than\nwaiting for ``status`` to change. No renewal is charged. Once\n``current_period_end`` has passed and no charge is still in progress, a\nbackground job makes the subscription ``canceled`` with\n``cancellation_reason: \"period_end\"`` and ``canceled_at`` set to the period\nend, and ``subscription.canceled`` fires.\n\nThere is no option to cancel immediately. If the price has\n``refund_on_cancel`` set to ``full`` or ``prorated``, the refund is\nissued and access ends now; otherwise refund the payment in full to end\nit now. Cancelling an already cancelled subscription returns it\nunchanged. The customer is emailed if they have an address on file. A\ncharge in progress for the customer returns 409 ``operation_pending``,\nand so does a renewal payment still in progress (reason\n``renewal_processing``, naming when to retry).\n\nWhen ``current_period_end`` has already passed and the renewal was never\nsent (held for the SEPA notice, or retried later after a refusal that\nwas not the customer's), there is no period end left to cancel at: the\nsubscription is ``canceled`` at once, with ``cancellation_reason:\n\"period_end\"`` and ``canceled_at`` set to that period end, and the\nperiod after it is never charged.\n\nUndo with ``POST /v1/subscriptions/{id}/reactivate`` before the period\nends.", "operationId": "cancel_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Cancel Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:cancel" } }, "/v1/subscriptions/{subscription_id}/pause": { "post": { "description": "Stop a subscription renewing without cancelling it.\n\nRenewals stop, any pending cancellation is cleared, and ``renewal_state``\nbecomes ``paused`` while ``status`` stays ``active``. The customer keeps\naccess until ``current_period_end`` (``serves_customer`` reflects this).\nResume with ``POST /v1/subscriptions/{id}/resume``, which is only\npossible before ``current_period_end``; after that the customer has to\ncheck out again. Once ``current_period_end`` has passed and no charge is\nstill in progress, a paused subscription becomes ``canceled`` and\n``subscription.canceled`` fires.\n\nPausing a cancelled or metered subscription returns 409 ``state_conflict``. Pausing a\n``past_due`` subscription returns 409 ``subscription_past_due``: the\nunpaid renewal has to be paid first. Pausing one that is already paused\nreturns it unchanged.", "operationId": "pause_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Pause Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:write" } }, "/v1/subscriptions/{subscription_id}/preview_update": { "post": { "description": "Quote what moving a subscription to another price would cost now.\n\nReturns the credit for the unused part of the current period, the amount\nthat would be charged now with tax shown separately, and the new period\nend. Nothing is written or charged.\n\nWhen ``refused`` is true, the credit nearly covers the new price because\nthe renewal is close, and ``POST /v1/subscriptions/{id}/update`` would\nreturn 409 ``state_conflict``; wait for the renewal instead. The quote is advisory: the\nupdate recalculates the amount at the time you call it.", "operationId": "preview_update_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanChangePreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanChangePreviewResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Preview Update Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:read" } }, "/v1/subscriptions/{subscription_id}/reactivate": { "post": { "description": "Undo a pending cancellation so the subscription keeps renewing.\n\nClears ``cancel_at_period_end`` and sets ``renewal_state`` back to\n``auto_renew``. The same conditions as resuming apply:\n``current_period_end`` must still be in the future and the customer\nmust have an authorised payment method, otherwise it returns 409\n``state_conflict``. A paused subscription is not scheduled to cancel, so\nreactivating it returns 409; restart it with ``POST /v1/subscriptions/{id}/resume``.\nEmits ``subscription.reactivated``. Reactivating a subscription that\nis already renewing returns it unchanged.", "operationId": "reactivate_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reactivate Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:write" } }, "/v1/subscriptions/{subscription_id}/reauthorize_payment_method": { "post": { "description": "Start the flow for a customer to replace their payment method.\n\nUse it when a renewal has failed or a card is about to expire. Send the\ncustomer to ``checkout_url`` in the response, where they authorise a new\npayment method with a small verification charge; its amount and currency\nare in the response. After the payment, they are sent to ``return_url``.\n\nNothing changes until the provider confirms that payment. Then the new\nmethod is stored, the next retry of a failed renewal charges it, and\n``subscription.payment_method_updated`` is sent. A cancelled\nsubscription, or one whose first checkout has not completed, returns 409\n``state_conflict``.\n\nFor a ``past_due`` subscription whose renewals BillKit charges itself,\nthe payment is not a verification: it is the unpaid renewal, at the\namount every retry charges (``verification_amount_cents`` is that\namount). Once paid the subscription is ``active`` again on the new\nmethod, and no retry is needed. Calling this again while that payment\npage is still open returns the same ``checkout_url``.", "operationId": "reauthorize_payment_method", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthorizationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthorizationResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reauthorize Payment Method", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:write" } }, "/v1/subscriptions/{subscription_id}/resume": { "post": { "description": "Restart renewals on a paused subscription.\n\nNothing is charged now; the next renewal falls at\n``current_period_end``. It returns 409 ``state_conflict`` if ``current_period_end`` has\nalready passed (start a new checkout instead) or if the customer has no\nauthorised payment method (send them through\n``POST /v1/subscriptions/{id}/reauthorize_payment_method`` first).\nA subscription scheduled to cancel is not paused, so resuming it\nreturns 409; withdraw the cancellation with\n``POST /v1/subscriptions/{id}/reactivate``. Emits\n``subscription.resumed``. Resuming a subscription that is already\nrenewing returns it unchanged.", "operationId": "resume_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Resume Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:write" } }, "/v1/subscriptions/{subscription_id}/update": { "post": { "description": "Move a subscription to a different price, charging the prorated difference.\n\nThis starts the change. The difference is charged to the customer's\nstored payment method, and ``price_id`` changes only once that payment\nsucceeds, so the response still shows the old price. Wait for the\n``subscription.updated`` event, or read the subscription until\n``price_id`` changes.\n\nThe amount is recalculated here, not taken from a preview. The\nsubscription must be renewing normally (not paused or cancelling) and\nhave an authorised payment method. The new price must be active and in\nthe same currency, and neither price may be metered. A change so close\nto renewal that the credit nearly covers the new price returns 409\n``state_conflict``, as does a subscription that is not renewing or has no\npayment method. A\ncharge already in progress for the customer returns 409\n``operation_pending``.", "operationId": "update_subscription", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanChangeUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Subscription", "tags": [ "subscriptions" ], "x-required-scope": "subscriptions:write" } }, "/v1/subscriptions/{subscription_id}/usage_records": { "get": { "description": "List the usage reported against one metered subscription.\n\nPass ``invoice_id=pending`` for records the next period close will bill,\nor an invoice id for the records billed on that invoice. Without the\nfilter every record is returned.\n\nRecords with ``written_off_at`` set will never be billed, because the\nsubscription stopped billing before they were invoiced, and are left out\nof ``pending``. A subscription that is not metered returns 409; one\nbelonging to another account returns 404.", "operationId": "list_usage_records", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "Filter by billing state: 'pending' for records not yet invoiced, or an invoice id for the records it billed.", "in": "query", "name": "invoice_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Filter by billing state: 'pending' for records not yet invoiced, or an invoice id for the records it billed.", "title": "Invoice Id" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_UsageRecordResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Usage Records", "tags": [ "usage_records" ], "x-required-scope": "usage_records:read" }, "post": { "description": "Report usage against a metered subscription.\n\nPost a record whenever the customer uses something you charge for.\nNothing is charged now: pending records are added up when the monthly\nperiod closes and billed as one invoice line.\n\nThe subscription must be on a metered price and be ``active`` or\n``past_due``, otherwise the call returns 409 ``state_conflict``. ``occurred_at`` defaults to\nnow and may be backdated within the subscription's lifetime, but not set\nin the future.\n\nRecords cannot be changed or deleted, so deduplicate as you send. An\n``Idempotency-Key`` header protects a retry of the same HTTP request.\n``identifier`` protects against your own system reporting the same usage\ntwice with different requests, for example a job that runs again: send\nthe id of the thing you are metering, and a second record with the same\n``identifier`` on this subscription returns the first one unchanged.", "operationId": "create_usage_record", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Usage Record", "tags": [ "usage_records" ], "x-required-scope": "usage_records:write" } }, "/v1/subscriptions/{subscription_id}/usage_summary": { "get": { "description": "See what the next period close will bill for a metered subscription.\n\nPrices the pending usage the way the close will, returning\n``net_cents``, ``tax_cents`` and ``gross_cents`` for the current\nperiod. ``will_charge`` is false when there is nothing to bill or the\ntotal is below ``minimum_charge_cents``, the payment provider's minimum.\nUsage below the minimum is not lost: it stays pending and is billed with\nthe next period. ``open_invoice_id`` names an earlier invoice that is\nstill unpaid; this period cannot be charged while it is open. A\nsubscription that is not metered returns 409.", "operationId": "get_usage_summary", "parameters": [ { "description": "Id of the subscription, which starts ``sub_``.", "in": "path", "name": "subscription_id", "required": true, "schema": { "description": "Id of the subscription, which starts ``sub_``.", "title": "Subscription Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Usage Summary", "tags": [ "usage_records" ], "x-required-scope": "usage_records:read" } }, "/v1/tax_rates": { "get": { "description": "List tax rates, newest first.\n\nRetired rates are included with ``active: false``, so a country can\nappear more than once. The one that applies today is the active one.", "operationId": "list_tax_rates", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_TaxRateResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Tax Rates", "tags": [ "tax_rates" ], "x-required-scope": "tax_rates:read" }, "post": { "description": "Set the VAT rate to charge customers in one country.\n\nConfigure a rate for each country you sell into. Without one, customers\nthere are charged no tax. The rate is in basis points, so 2100 means 21\npercent. ``inclusive`` says whether your prices already contain the tax\nor it should be added on top.\n\nCreating a rate for a country that already has one automatically retires\nthe old rate rather than replacing it. The old row is kept so charges\nmade under it still reconcile. Rates apply to charges made from now on\nand never reprice anything already invoiced.", "operationId": "create_tax_rate", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Tax Rate", "tags": [ "tax_rates" ], "x-required-scope": "tax_rates:write" } }, "/v1/tax_rates/{tax_rate_id}": { "get": { "description": "Retrieve one tax rate.\n\nRetired rates are still readable, with ``active: false``, so a charge can\nbe traced back to the rate it was made under. A rate belonging to\nanother account returns 404, not 403.", "operationId": "get_tax_rate", "parameters": [ { "description": "Id of the tax rate, which starts ``tr_``.", "in": "path", "name": "tax_rate_id", "required": true, "schema": { "description": "Id of the tax rate, which starts ``tr_``.", "title": "Tax Rate Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Tax Rate", "tags": [ "tax_rates" ], "x-required-scope": "tax_rates:read" }, "post": { "description": "Correct a tax rate, retire it, or bring a retired one back into use.\n\nOnly the fields you send change, and the country cannot be changed at\nall. Prefer creating a new rate when a country's VAT genuinely changes,\nso the old charges stay traceable to the rate that produced them; edit in\nplace only to fix a rate that was entered wrong. ``display_name: null``\nremoves the display name; ``null`` on any other field returns 400\nnaming the field, because none of them can be cleared.\n\nSending ``active: false`` retires the rate and is how you stop charging\nVAT in a country. The rate stays readable, because an invoice records\nthe percentage it charged and you have to be able to point at the rate\nthat produced it. If it was the country's only active rate, customers\nthere are charged no tax from then on, so retire only when you genuinely\nstop collecting VAT in that country.\n\nSending ``active: true`` on a retired rate makes it current again and\nretires whichever rate currently holds that country, since a country can\nonly have one active rate. Nothing already invoiced is repriced.", "operationId": "update_tax_rate", "parameters": [ { "description": "Id of the tax rate, which starts ``tr_``.", "in": "path", "name": "tax_rate_id", "required": true, "schema": { "description": "Id of the tax rate, which starts ``tr_``.", "title": "Tax Rate Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Tax Rate", "tags": [ "tax_rates" ], "x-required-scope": "tax_rates:write" } }, "/v1/tenant/billing_profile": { "get": { "description": "Read your own business country, VAT number and invoice address.\n\nYour country decides the VAT on your customers' charges, so check it\nbefore your first live payment. ``country_code`` is what you have stored\nand can be null; ``effective_country_code`` is what the next charge will\nuse. They differ only when you have stored nothing, which is the case to\nfix. ``vat_id`` is your own VAT registration, or null.", "operationId": "get_billing_profile", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBillingProfileResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Billing Profile", "tags": [ "tenant" ], "x-required-scope": "tenant:read" }, "post": { "description": "Set your business country, and optionally your VAT number and invoice address.\n\nSet this before you charge anyone: your country decides whether a sale\nis domestic, cross-border within the EU or outside it, and so which VAT\napplies.\n\n``country_code`` is required on every call. ``legal_name``, the address\nfields and ``registration_number`` are optional: omit one to leave it\nunchanged, or send ``null`` to clear it. BillKit's own invoices to you\nare issued only once ``legal_name``, ``address_line1`` and ``city`` are\nset.\n\n``vat_id`` can be set once. A new number is checked against the EU VIES\nregister for your country and refused with 400 ``vat_not_recognised``\nif VIES says it is not valid; if VIES cannot be reached it is stored\nand checked again later. Once stored it cannot be changed or cleared\nhere: sending a different value returns 400 ``vat_id_locked``, and\nre-sending the same number is accepted. Contact support to change it.\n\nAn invalid country code or VAT number format returns 400. Changes apply\nfrom your next charge; issued documents are never recalculated.\n\nYour billing identity is shared by live and test mode, so a test-mode\nAPI key cannot change it: call with a live-mode key, or change it from\nthe dashboard. A test key gets 403 ``mode_mismatch``.", "operationId": "update_billing_profile", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBillingProfileUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBillingProfileResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Billing Profile", "tags": [ "tenant" ], "x-required-scope": "tenant:write" } }, "/v1/tenant/capabilities": { "get": { "description": "Read which payment methods and currencies your account can use in the current mode.\n\nWhat you can accept depends on what your payment provider has enabled\nfor your account, so check this before offering a method.\n``allowed_currencies`` are the currencies your BillKit account accepts;\n``mollie_connected`` says whether a provider account is connected.\n\nThe provider lists are cached and refreshed in the background;\n``provider_capabilities_refreshed_at`` says when. Until the first refresh\nthat timestamp is null and both lists are empty, which means \"not known\nyet\" rather than \"nothing enabled\", so check again shortly.", "operationId": "get_tenant_capabilities", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCapabilitiesResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Tenant Capabilities", "tags": [ "tenant" ], "x-required-scope": "tenant:read" } }, "/v1/tenant/export": { "get": { "description": "Download all of your account's data in the current mode as one JSON file.\n\nUse it for GDPR data portability, for backups, or to migrate. It\ncontains your products, prices, coupons and tax rates; customers and\nsubscriptions; subscription and one-off payments with their refunds,\ncredit notes and disputes; invoices with line items; usage records; and\nevents. Each record has the same shape as the matching ``GET`` endpoint\nreturns. ``billkit_export_version`` identifies the file format and is\ncurrently ``2``.\n\nThe response is streamed and can be large, so write it to a file. It\ncontains only the mode of the API key you call with; export test and\nlive separately. Each export is recorded in your audit log.\n\nFrom a dashboard session this needs a recent step-up (403\n``step_up_required`` otherwise); API keys with the ``data:export``\nscope are not asked.", "operationId": "export_tenant_data", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "description": "The export file, streamed: write it to disk rather than buffering it. `billkit_export_version` names its format; each collection holds records shaped like the matching `GET` endpoint's.", "properties": { "billkit_export_version": { "type": "integer" } }, "required": [ "billkit_export_version" ], "type": "object" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Export Tenant Data", "tags": [ "tenant" ], "x-required-scope": "data:export" } }, "/v1/tenant/portal_branding": { "get": { "description": "Read your billing portal branding.\n\nFields you have never set are returned as null rather than filled with\ndefaults, so a settings form can tell \"not configured\" from \"configured\".\n``effective_business_name`` and ``effective_support_email`` are what\ncustomers actually see.", "operationId": "get_portal_branding", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPortalBrandingResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Portal Branding", "tags": [ "tenant" ], "x-required-scope": "tenant:read" }, "post": { "description": "Set the business name, logo, support email, theme and features of your billing portal.\n\nOnly the fields you send change. Sending a field as ``null`` clears it,\nso the portal falls back to its default; omitting it leaves it alone.\n``logo_url`` must use ``https``. Changes apply to portal sessions that\nare already open.\n\nThe portal is shared by live and test mode, so a test-mode API key\ncannot change it: call with a live-mode key, or change it from the\ndashboard. A test key gets 403 ``mode_mismatch``.", "operationId": "update_portal_branding", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPortalBrandingUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPortalBrandingResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Portal Branding", "tags": [ "tenant" ], "x-required-scope": "tenant:write" } }, "/v1/tenant/provider_credential": { "post": { "description": "Replace the payment provider API key BillKit uses to charge on your behalf.\n\nUse it after rotating the key at your provider so charges keep working.\nThe key is stored encrypted and never returned. Sending the same key\nagain is harmless.\n\nOne key is held per mode, and an API key can only replace the one for\nits own mode: a test key replaces the test provider key and a live key\nthe live one. ``mode`` is optional; if you send it, it must match the\nmode of the API key you call with, or the request fails with 403\n``mode_mismatch``. To replace the other mode's key, call with that\nmode's API key or use the dashboard. A wrong key stops charges in that\nmode, so check it with your provider first.", "operationId": "rotate_tenant_provider_credential", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProviderCredentialRotateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProviderCredentialResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Rotate Tenant Provider Credential", "tags": [ "tenant" ], "x-required-scope": "provider_credential:write" } }, "/v1/test_clocks": { "get": { "description": "List your test clocks, newest first. Test mode only; a live-mode key gets 403.", "operationId": "list_test_clocks", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_TestClockResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Test Clocks", "tags": [ "test_clocks" ], "x-required-scope": "test_clocks:read" }, "post": { "description": "Create a test clock, frozen at ``frozen_time``, to test billing over time.\n\nAttach customers to it by passing its id as ``test_clock_id`` when you\ncreate them, then advance it to see trials end, renewals fall due and\ndunning run without waiting. Only customers created that way follow the\nclock. Test clocks exist only in test mode; a live-mode key gets 403 ``mode_mismatch``.", "operationId": "create_test_clock", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Test Clock", "tags": [ "test_clocks" ], "x-required-scope": "test_clocks:write" } }, "/v1/test_clocks/{test_clock_id}": { "delete": { "description": "Delete a test clock.\n\nThe clock is removed and the response is a deletion marker. Customers\nattached to it are not deleted; they are detached and return to real\ntime. Test mode only.", "operationId": "delete_test_clock", "parameters": [ { "description": "Id of the test clock, which starts ``tc_``.", "in": "path", "name": "test_clock_id", "required": true, "schema": { "description": "Id of the test clock, which starts ``tc_``.", "title": "Test Clock Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete Test Clock", "tags": [ "test_clocks" ], "x-required-scope": "test_clocks:write" }, "get": { "description": "Retrieve one test clock and the time it is currently frozen at.\n\nTest mode only. A clock belonging to another account returns 404.", "operationId": "get_test_clock", "parameters": [ { "description": "Id of the test clock, which starts ``tc_``.", "in": "path", "name": "test_clock_id", "required": true, "schema": { "description": "Id of the test clock, which starts ``tc_``.", "title": "Test Clock Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Test Clock", "tags": [ "test_clocks" ], "x-required-scope": "test_clocks:read" } }, "/v1/test_clocks/{test_clock_id}/advance": { "post": { "description": "Move a test clock forward and run everything that falls due in between.\n\nAdvancing past a trial end, a metered period close, a dunning deadline or\na one-off payment's expiry makes each of them happen, for this clock's\ncustomers only. The work finishes before the response, so you can read\nthe results straight away.\n\n``frozen_time`` must be later than the clock's current time, otherwise\nthe call returns 400. A renewal that falls due is charged on the stored\npayment method through Mollie in test mode, so no real money moves; the\npayment's result arrives from Mollie in real time, as usual. Test mode\nonly.\n\nSend an ``Idempotency-Key`` to make a retry safe: a repeat with the same\nkey returns the first response instead of advancing again. Without one,\na repeat to the same ``frozen_time`` returns 400, because the clock has\nalready moved there.", "operationId": "advance_test_clock", "parameters": [ { "description": "Id of the test clock, which starts ``tc_``.", "in": "path", "name": "test_clock_id", "required": true, "schema": { "description": "Id of the test clock, which starts ``tc_``.", "title": "Test Clock Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockAdvance" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClockResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Advance Test Clock", "tags": [ "test_clocks" ], "x-required-scope": "test_clocks:write" } }, "/v1/webhook_endpoints": { "get": { "description": "List your webhook endpoints, newest first.\n\nDisabled endpoints are included, so check ``status`` to see which are\nactually receiving events. Deleted ones are not: they are gone.", "operationId": "list_webhook_endpoints", "parameters": [ { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WebhookEndpointResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Webhook Endpoints", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:read" }, "post": { "description": "Register a URL to receive events.\n\nMost outcomes, such as a payment succeeding, a renewal or a refund\nsettling, happen after the API call that started them, and webhooks are\nhow you hear about them. Register an endpoint before your first live\npayment.\n\nThe signing secret is returned in this response only; store it and use\nit to verify that requests come from BillKit. ``enabled_events`` lists\nthe event types to send and defaults to ``[\"*\"]``, every event. An\nunknown event type returns 400, and so does a URL that points at a\nprivate or internal address. A mode holds at most 16 endpoints,\ndisabled ones included; creating one more returns 409\n``webhook_endpoint_limit_reached``.", "operationId": "create_webhook_endpoint", "parameters": [ { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create Webhook Endpoint", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:write" } }, "/v1/webhook_endpoints/event_types": { "get": { "description": "List every event type you can subscribe a webhook endpoint to.\n\n``enabled_events`` rejects any name not on this list, so read it here\nrather than hard-coding a set. ``wildcard`` is the value that subscribes\nto every event, including types added later. Requires the\n``webhook_endpoints:read`` scope.", "operationId": "list_event_types", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeListResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Event Types", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:read" } }, "/v1/webhook_endpoints/{endpoint_id}": { "delete": { "description": "Delete a webhook endpoint.\n\nThe endpoint stops receiving events, ``GET /v1/webhook_endpoints/{id}``\nreturns 404, and it is left out of listings. This cannot be undone, and\nthe response is a deletion marker. Its delivery attempts are deleted with\nit; the events remain available from ``GET /v1/events``.\n\nTo stop delivery temporarily, set ``status: \"disabled\"`` with\n``POST /v1/webhook_endpoints/{id}`` instead, which keeps the endpoint,\nits signing secret and its history.", "operationId": "delete_webhook_endpoint", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResource" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete Webhook Endpoint", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:write" }, "get": { "description": "Retrieve one webhook endpoint's configuration.\n\nThe signing secret is not returned; only the fingerprint of it, which is\nenough to tell which secret is current after a rotation. An endpoint\nbelonging to another account returns 404, not 403.", "operationId": "get_webhook_endpoint", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Webhook Endpoint", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:read" }, "post": { "description": "Update a webhook endpoint's URL, event list, description or status.\n\nOnly the fields you send change. ``enabled_events`` is replaced\nwholesale, not merged, so send the complete list you want.\n``description: null`` removes the description; ``null`` on ``url``,\n``enabled_events`` or ``status`` returns 400 naming the field, because\nnone of them can be cleared.\n\nSetting ``status`` to ``disabled`` stops delivery while keeping the\nendpoint, its signing secret and its delivery history, for planned\ndowntime or while you investigate a failing receiver. Deliveries that\nfall due while it is disabled are marked ``failed``; redeliver them once\nit is enabled again. Use ``DELETE /v1/webhook_endpoints/{id}`` when the\nendpoint should not exist at all; disabling is reversible and deleting\nis not.\n\nChanging the URL does not change the signing secret, so your receiver\nkeeps verifying with the same one. Deliveries already queued and not yet\nsent will go to the new URL, so point it somewhere ready to receive them.", "operationId": "update_webhook_endpoint", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update Webhook Endpoint", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:write" } }, "/v1/webhook_endpoints/{endpoint_id}/deliveries": { "get": { "description": "List the delivery attempts made to one webhook endpoint, newest first.\n\nThis is where you go when a webhook did not arrive. Each row shows the\nstatus code your receiver returned, an excerpt of its response body, how\nmany attempts have been made, and when the next one is due. It tells you\nwhether the problem is on our side or yours without needing our help.", "operationId": "list_webhook_endpoint_deliveries", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "Maximum number of objects to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Maximum number of objects to return.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Cursor for pagination: the id of the last object on the previous page. Returns the objects listed after it. An id that names no such object is a 400.", "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WebhookDeliveryResponse_" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "List Webhook Endpoint Deliveries", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:read" } }, "/v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}": { "get": { "description": "Retrieve one delivery attempt.\n\nRead the status, response code, body excerpt and error on a single\nattempt before deciding whether to send it again. A delivery belonging to\nanother account, or to a different endpoint, returns 404.", "operationId": "get_webhook_delivery", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "Id of the webhook delivery, which starts ``whd_``.", "in": "path", "name": "delivery_id", "required": true, "schema": { "description": "Id of the webhook delivery, which starts ``whd_``.", "title": "Delivery Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } }, "description": "Successful Response", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get Webhook Delivery", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:read" } }, "/v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver": { "post": { "description": "Send one delivery again.\n\nUse it once your receiver is back up, to catch up on deliveries that\nfailed. The delivery is queued to be sent within moments rather than\nsent during this request, so a 200 means it is scheduled, not that it\narrived. The attempt count is kept, not reset.\n\nA delivery that already succeeded is returned unchanged rather than sent\ntwice. A delivery being sent at this moment returns 409\n``operation_pending``: that attempt is already the send you asked for,\nso retry once it has finished. A disabled endpoint returns 409\n``webhook_endpoint_disabled``; enable it first.", "operationId": "redeliver_webhook_delivery", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "Id of the webhook delivery, which starts ``whd_``.", "in": "path", "name": "delivery_id", "required": true, "schema": { "description": "Id of the webhook delivery, which starts ``whd_``.", "title": "Delivery Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Redeliver Webhook Delivery", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:write" } }, "/v1/webhook_endpoints/{endpoint_id}/rotate_secret": { "post": { "description": "Replace the endpoint's signing secret.\n\nRotate when a secret may have leaked, or on whatever schedule your own\npolicy sets. The new secret is returned once in this response and never\nagain, so store it before you do anything else.\n\nYou do not have to deploy the new secret instantly. The previous one\nkeeps verifying signatures for 24 hours, so roll it out at your own pace\nwithin that window; after it your receiver must be using the new one.\nRotating again inside the window discards the older secret, so do not\nrotate twice in quick succession.", "operationId": "rotate_webhook_endpoint_secret", "parameters": [ { "description": "Id of the webhook endpoint, which starts ``we_``.", "in": "path", "name": "endpoint_id", "required": true, "schema": { "description": "Id of the webhook endpoint, which starts ``we_``.", "title": "Endpoint Id", "type": "string" } }, { "description": "A unique key, up to 255 characters, that makes this request safe to retry. A repeat with the same key and the same body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of running again; the same key with a different body is refused with `409 idempotency_key_in_use`. A JSON body is compared as JSON, so key order and whitespace do not make it different. Optional: omitted, the request runs normally. Present but blank is refused with a 400.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was refused (`type: invalid_request_error`): a required parameter is missing (`parameter_missing`), one failed validation (`parameter_invalid`) or is not one the operation takes (`parameter_unknown`), and `param` names it.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No credential, or one that does not authenticate.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account is suspended (`tenant_suspended`), or the payment provider refused a charge or refund the call made (`type: payment_error`, `code: payment_refused`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authenticated, but not allowed: missing scope (`insufficient_scope`), a key of the wrong mode (`mode_mismatch`), or a refused origin.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such object in this account and mode.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the object's current state (`state_conflict`, or a more specific code), or an operation still in flight (`operation_pending`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request body is larger than the API accepts.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited. `Retry-After` says when to try again.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Something failed on BillKit's side (`type: api_error`). Retry with the same `Idempotency-Key`.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The payment provider failed or did not answer.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporarily unable to serve. `reason` says whether the request was attempted.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } } }, "security": [ { "ApiKey": [] } ], "summary": "Rotate Webhook Endpoint Secret", "tags": [ "webhook_endpoints" ], "x-required-scope": "webhook_endpoints:write" } } }, "security": [ { "ApiKey": [] } ], "servers": [ { "url": "https://api.billkit.eu" } ], "webhooks": { "checkout.session.completed": { "post": { "description": "`data` is a `CheckoutSessionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCompletedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "checkout.session.completed", "tags": [ "webhooks" ] } }, "checkout.session.expired": { "post": { "description": "`data` is a `CheckoutSessionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionExpiredEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "checkout.session.expired", "tags": [ "webhooks" ] } }, "coupon.created": { "post": { "description": "`data` is a `CouponResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "coupon.created", "tags": [ "webhooks" ] } }, "coupon.updated": { "post": { "description": "`data` is a `CouponResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "coupon.updated", "tags": [ "webhooks" ] } }, "credit_note.created": { "post": { "description": "`data` is a `CreditNoteResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "credit_note.created", "tags": [ "webhooks" ] } }, "customer.created": { "post": { "description": "`data` is a `CustomerResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "customer.created", "tags": [ "webhooks" ] } }, "customer.deleted": { "post": { "description": "`data` is a `CustomerResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDeletedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "customer.deleted", "tags": [ "webhooks" ] } }, "customer.updated": { "post": { "description": "`data` is a `CustomerResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "customer.updated", "tags": [ "webhooks" ] } }, "dispute.closed": { "post": { "description": "`data` is a `DisputeResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeClosedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "dispute.closed", "tags": [ "webhooks" ] } }, "dispute.created": { "post": { "description": "`data` is a `DisputeResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "dispute.created", "tags": [ "webhooks" ] } }, "dunning.email_required": { "post": { "description": "`data` is a `DunningNotification`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DunningEmailRequiredEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "dunning.email_required", "tags": [ "webhooks" ] } }, "invoice.created": { "post": { "description": "`data` is a `InvoiceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.created", "tags": [ "webhooks" ] } }, "invoice.marked_uncollectible": { "post": { "description": "`data` is a `InvoiceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceMarkedUncollectibleEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.marked_uncollectible", "tags": [ "webhooks" ] } }, "invoice.paid": { "post": { "description": "`data` is a `InvoiceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaidEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.paid", "tags": [ "webhooks" ] } }, "invoice.payment_failed": { "post": { "description": "`data` is a `InvoiceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentFailedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.payment_failed", "tags": [ "webhooks" ] } }, "invoice.upcoming": { "post": { "description": "`data` is a `UpcomingInvoice`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceUpcomingEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.upcoming", "tags": [ "webhooks" ] } }, "invoice.voided": { "post": { "description": "`data` is a `InvoiceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceVoidedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "invoice.voided", "tags": [ "webhooks" ] } }, "one_shot_payment.failed": { "post": { "description": "`data` is a `OneShotPaymentResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentFailedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "one_shot_payment.failed", "tags": [ "webhooks" ] } }, "one_shot_payment.refunded": { "post": { "description": "`data` is a `OneShotPaymentResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentRefundedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "one_shot_payment.refunded", "tags": [ "webhooks" ] } }, "one_shot_payment.succeeded": { "post": { "description": "`data` is a `OneShotPaymentResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotPaymentSucceededEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "one_shot_payment.succeeded", "tags": [ "webhooks" ] } }, "payment.failed": { "post": { "description": "`data` is a `PaymentResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentFailedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "payment.failed", "tags": [ "webhooks" ] } }, "payment.succeeded": { "post": { "description": "`data` is a `PaymentResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSucceededEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "payment.succeeded", "tags": [ "webhooks" ] } }, "price.archived": { "post": { "description": "`data` is a `PriceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceArchivedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "price.archived", "tags": [ "webhooks" ] } }, "price.created": { "post": { "description": "`data` is a `PriceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "price.created", "tags": [ "webhooks" ] } }, "price.updated": { "post": { "description": "`data` is a `PriceResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "price.updated", "tags": [ "webhooks" ] } }, "product.archived": { "post": { "description": "`data` is a `ProductResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductArchivedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "product.archived", "tags": [ "webhooks" ] } }, "product.created": { "post": { "description": "`data` is a `ProductResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "product.created", "tags": [ "webhooks" ] } }, "product.updated": { "post": { "description": "`data` is a `ProductResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "product.updated", "tags": [ "webhooks" ] } }, "refund.created": { "post": { "description": "`data` is a `RefundResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "refund.created", "tags": [ "webhooks" ] } }, "refund.failed": { "post": { "description": "`data` is a `RefundResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundFailedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "refund.failed", "tags": [ "webhooks" ] } }, "refund.succeeded": { "post": { "description": "`data` is a `RefundResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundSucceededEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "refund.succeeded", "tags": [ "webhooks" ] } }, "subscription.canceled": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCanceledEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.canceled", "tags": [ "webhooks" ] } }, "subscription.coupon_applied": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCouponAppliedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.coupon_applied", "tags": [ "webhooks" ] } }, "subscription.coupon_expired": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCouponExpiredEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.coupon_expired", "tags": [ "webhooks" ] } }, "subscription.created": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.created", "tags": [ "webhooks" ] } }, "subscription.past_due": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPastDueEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.past_due", "tags": [ "webhooks" ] } }, "subscription.paused": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPausedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.paused", "tags": [ "webhooks" ] } }, "subscription.payment_method_updated": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentMethodUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.payment_method_updated", "tags": [ "webhooks" ] } }, "subscription.plan_changed": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanChangedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.plan_changed", "tags": [ "webhooks" ] } }, "subscription.reactivated": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionReactivatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.reactivated", "tags": [ "webhooks" ] } }, "subscription.resumed": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResumedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.resumed", "tags": [ "webhooks" ] } }, "subscription.trial_ended": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionTrialEndedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.trial_ended", "tags": [ "webhooks" ] } }, "subscription.trial_started": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionTrialStartedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.trial_started", "tags": [ "webhooks" ] } }, "subscription.trial_will_end": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionTrialWillEndEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.trial_will_end", "tags": [ "webhooks" ] } }, "subscription.updated": { "post": { "description": "`data` is a `SubscriptionResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "subscription.updated", "tags": [ "webhooks" ] } }, "webhook_endpoint.created": { "post": { "description": "`data` is a `WebhookEndpointResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "webhook_endpoint.created", "tags": [ "webhooks" ] } }, "webhook_endpoint.deleted": { "post": { "description": "`data` is a `WebhookEndpointResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDeletedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "webhook_endpoint.deleted", "tags": [ "webhooks" ] } }, "webhook_endpoint.updated": { "post": { "description": "`data` is a `WebhookEndpointResponse`.", "parameters": [ { "description": "`t=,v1=`, the HMAC of `.` under the endpoint's signing secret. During a secret rotation it carries one `v1` per live secret: accept the delivery if any of them matches.", "in": "header", "name": "BillKit-Signature", "required": true, "schema": { "type": "string" } }, { "description": "The event's `evt_` id, the same as `id` in the body. Deduplicate on it.", "in": "header", "name": "BillKit-Event-Id", "required": true, "schema": { "type": "string" } }, { "description": "The same as `type` in the body, so you can route before parsing.", "in": "header", "name": "BillKit-Event-Type", "required": true, "schema": { "type": "string" } }, { "description": "1 on the first attempt, incrementing on each retry.", "in": "header", "name": "BillKit-Delivery-Attempt", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdatedEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Acknowledge the delivery. Anything else, or no answer within the delivery timeout, is retried on the backoff schedule." } }, "security": [], "summary": "webhook_endpoint.updated", "tags": [ "webhooks" ] } } } }