{"openapi":"3.1.0","info":{"title":"Perly Pay API","version":"1.0.0","summary":"Crypto payments straight to your wallet: bitcoin and dollar stablecoins, 0% of volume.","description":"Authenticate with your secret key: `Authorization: Bearer sk_test_…` (test mode) or `sk_live_…`. The key decides the mode. Amounts in fiat are integers in minor units (cents); on-chain amounts are integer strings in the asset's smallest unit. Send an `Idempotency-Key` with every POST so a retry never does a thing twice. Lists are newest first: pass `next_cursor` back as `cursor`."},"servers":[{"url":"https://pay.perly.io/api/v1"}],"tags":[{"name":"Invoices"},{"name":"Test mode"},{"name":"Checkout sessions"},{"name":"Products"},{"name":"Prices"},{"name":"Customers"},{"name":"Subscriptions"},{"name":"Payment links"},{"name":"Coupons"},{"name":"Entitlements"},{"name":"Credits"},{"name":"License keys"},{"name":"Buyer portal"},{"name":"Payments"},{"name":"Refunds"},{"name":"Receipts"},{"name":"Events"},{"name":"Webhook endpoints"}],"paths":{"/invoices":{"post":{"operationId":"createInvoice","summary":"Create an invoice","description":"Lines are prices (`{ price, quantity }`) or your own (`{ description, amount, quantity }`), in one currency. For a single amount, `amount` + `description` is short for one line. `customer` is an id or `{ email }`. A price line may carry its own `description` (\"Seat #12\"), and `discount` takes an amount off this invoice alone. The buyer pays at `url`, choosing bitcoin or a stablecoin there. Live mode: once a calendar month's paid sales pass the plan's limit and its 10% buffer, a new invoice is refused with 403 `plan_limit_reached` until the plan moves up; invoices already made are still paid.","tags":["Invoices"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"price":{"description":"A price id, `price_…`.","type":"string","maxLength":80},"quantity":{"type":"integer","minimum":1,"maximum":100000},"custom_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Pay-what-you-want: the amount per unit in minor units (cents), an integer."},"description":{"description":"Default: the product's name.","type":"string","minLength":1,"maxLength":300}},"required":["price"],"additionalProperties":false},{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":300},"amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Price per unit in minor units (cents), an integer."},"quantity":{"type":"integer","minimum":1,"maximum":100000}},"required":["description","amount"],"additionalProperties":false}]}},"amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"One amount instead of line_items in minor units (cents), an integer."},"description":{"description":"With `amount`: what it is for.","type":"string","minLength":1,"maxLength":300},"currency":{"description":"For lines without a price. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"customer":{"description":"A customer id, or `{ email }` to find or make one.","anyOf":[{"description":"A customer id, `cus_…`.","type":"string","maxLength":80},{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"],"additionalProperties":false}]},"customer_email":{"description":"Without `customer`: finds or makes the customer by email.","type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"coupon":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,40}$"},"discount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"A one-off amount off this invoice (a credit you owe the buyer; not with `coupon`) in minor units (cents), an integer."},"subscription":{"description":"A subscription id, `sub_…`.","type":"string","maxLength":80},"return_url":{"description":"Where the buyer's page sends them back.","type":"string","maxLength":2000,"format":"uri"},"expires_in_minutes":{"description":"Until when a rail may be chosen.","type":"integer","minimum":30,"maximum":129600},"locale":{"type":"string","pattern":"^[a-z]{2}$"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listInvoices","summary":"List invoices","tags":["Invoices"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","seen","underpaid","paid","overpaid","review","expired","canceled","refunded","partially_refunded"]}},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"subscription","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A subscription id, `sub_…`."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/invoices/{id}":{"get":{"operationId":"retrieveInvoice","summary":"Retrieve an invoice","tags":["Invoices"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/invoices/{id}/cancel":{"post":{"operationId":"cancelInvoice","summary":"Cancel an invoice","description":"Only while nothing has arrived. Money that arrives later is still seen (the address stays watched) and lands in review.","tags":["Invoices"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/invoices/{id}/simulate":{"post":{"operationId":"simulatePayment","summary":"Simulate a payment (test mode only)","description":"Test keys only. `full` pays the amount due: the invoice turns paid and is fulfilled — entitlements, license keys, a receipt, and the events your webhooks get. `short` sends half (underpaid), `over` a tenth more (overpaid); those two need the buyer's chain and asset chosen first. For `full`, an invoice with no chain yet gets one: `chain` and `asset` if given, else the first stablecoin offered (refund terms count as accepted).","tags":["Test mode"],"security":[{"secretKey":[]}],"x-test-mode-only":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"description":"Default full.","type":"string","enum":["full","short","over"]},"chain":{"type":"string","maxLength":40},"asset":{"type":"string","enum":["BTC","USDC","USDT"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/checkout_sessions":{"post":{"operationId":"createCheckoutSession","summary":"Create a checkout session","description":"A cart of 1–20 prices in one currency. Send the buyer to `url`, or open it in an overlay with pay.js (`data-session=\"cs_…\"`). The buyer comes back to `return_url` after paying, `cancel_url` if they leave. Live mode: once a calendar month's paid sales pass the plan's limit and its 10% buffer, a new session is refused with 403 `plan_limit_reached` until the plan moves up.","tags":["Checkout sessions"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"price":{"description":"A price id, `price_…`.","type":"string","maxLength":80},"quantity":{"type":"integer","minimum":1,"maximum":1000},"custom_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Pay-what-you-want: the amount per unit in minor units (cents), an integer."}},"required":["price"],"additionalProperties":false}},"return_url":{"type":"string","maxLength":2000,"format":"uri","description":"An http(s) URL."},"cancel_url":{"type":"string","maxLength":2000,"format":"uri","description":"An http(s) URL."},"customer":{"description":"A customer id, `cus_…`.","type":"string","maxLength":80},"customer_email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"coupon":{"description":"A coupon code.","type":"string","pattern":"^[A-Za-z0-9_-]{3,40}$"},"expires_in_minutes":{"description":"Default 1440 (24 hours).","type":"integer","minimum":30,"maximum":1440},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"required":["line_items"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listCheckoutSessions","summary":"List checkout sessions","tags":["Checkout sessions"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","complete","expired"]}},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutSession"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/checkout_sessions/{id}":{"get":{"operationId":"retrieveCheckoutSession","summary":"Retrieve a checkout session","tags":["Checkout sessions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/checkout_sessions/{id}/expire":{"post":{"operationId":"expireCheckoutSession","summary":"Expire a checkout session","description":"The buyer can no longer pay it. Only an open session.","tags":["Checkout sessions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/embed/checkout_sessions/{id}":{"get":{"operationId":"openCheckoutSession","summary":"Open a checkout session's page","description":"Public. Redirects (302) to the session's hosted checkout. pay.js uses it; `origin` (your page's origin) marks it as embedded so the page can talk back to pay.js.","tags":["Checkout sessions"],"security":[{},{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"origin","in":"query","required":false,"schema":{"type":"string","maxLength":300}}],"responses":{"302":{"description":"A redirect (Location) to the page."},"default":{"$ref":"#/components/responses/Error"}}}},"/products":{"post":{"operationId":"createProduct","summary":"Create a product","tags":["Products"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":2000},"image_url":{"type":"string","maxLength":2000,"format":"uri"},"issues_license":{"description":"Issue a license key with every purchase.","type":"boolean"},"license_activation_limit":{"description":"Instances a key may be active on.","type":"integer","minimum":1,"maximum":10000},"active":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listProducts","summary":"List products","tags":["Products"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/products/{id}":{"get":{"operationId":"retrieveProduct","summary":"Retrieve a product","tags":["Products"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateProduct","summary":"Update a product","description":"Set `active: false` to stop selling it; products are never deleted (invoices point at them).","tags":["Products"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","maxLength":2000,"format":"uri"},{"type":"null"}]},"issues_license":{"description":"Issue a license key with every purchase.","type":"boolean"},"license_activation_limit":{"anyOf":[{"description":"Instances a key may be active on.","type":"integer","minimum":1,"maximum":10000},{"type":"null"}]},"active":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/prices":{"post":{"operationId":"createPrice","summary":"Create a price","description":"Every model: one_time, pay_what_you_want (with a minimum), fixed_term (N days of access), subscription (interval, trial, grace, prepay), lifetime (optional cap and cohort tiers), credit_pack. Amounts are immutable; make a new price to change one.","tags":["Prices"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"one_time"},"unit_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Amount in minor units (cents), an integer."}},"required":["product","model","unit_amount"],"additionalProperties":false},{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"pay_what_you_want"},"custom_amount":{"type":"object","properties":{"minimum":{"type":"integer","minimum":1,"maximum":100000000000,"description":"The least a buyer may pay in minor units (cents), an integer."},"suggested":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Shown first in minor units (cents), an integer."}},"required":["minimum"],"additionalProperties":false}},"required":["product","model","custom_amount"],"additionalProperties":false},{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"fixed_term"},"unit_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Amount in minor units (cents), an integer."},"term_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Days of access one purchase gives."}},"required":["product","model","unit_amount","term_days"],"additionalProperties":false},{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"subscription"},"unit_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Price per period in minor units (cents), an integer."},"recurring":{"type":"object","properties":{"interval":{"type":"string","enum":["day","week","month","quarter","year","custom_days"]},"interval_days":{"description":"Days per period, with interval `custom_days`.","type":"integer","minimum":1,"maximum":3650},"trial_days":{"type":"integer","minimum":0,"maximum":365},"grace_days":{"description":"Days after the period ends before access stops. Default 3.","type":"integer","minimum":0,"maximum":60},"prepay_max_periods":{"description":"How many periods a buyer may pay ahead.","type":"integer","minimum":1,"maximum":36},"keep_renewal_price":{"description":"A renewal keeps the price first paid. Default true.","type":"boolean"}},"required":["interval"],"additionalProperties":false}},"required":["product","model","unit_amount","recurring"],"additionalProperties":false},{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"lifetime"},"unit_amount":{"description":"One price for every seat — or give `lifetime.tiers`.","type":"integer","minimum":1,"maximum":100000000000},"lifetime":{"type":"object","properties":{"quantity_cap":{"description":"How many are ever sold.","type":"integer","minimum":1,"maximum":10000000},"tiers":{"description":"Cohorts in order: the first `seats` sell at the first price…","minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"seats":{"type":"integer","minimum":1,"maximum":1000000},"unit_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Price per seat in minor units (cents), an integer."}},"required":["name","seats","unit_amount"],"additionalProperties":false}}},"additionalProperties":false}},"required":["product","model"],"additionalProperties":false},{"type":"object","properties":{"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"currency":{"description":"USD or EUR. Default: your account's currency.","type":"string","enum":["USD","EUR"]},"nickname":{"type":"string","minLength":1,"maxLength":60},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."},"model":{"type":"string","const":"credit_pack"},"unit_amount":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Amount in minor units (cents), an integer."},"credits":{"type":"integer","minimum":1,"maximum":100000000,"description":"Credits one pack holds."}},"required":["product","model","unit_amount","credits"],"additionalProperties":false}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listPrices","summary":"List prices","tags":["Prices"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."},{"name":"model","in":"query","required":false,"schema":{"type":"string","enum":["one_time","pay_what_you_want","fixed_term","subscription","lifetime","credit_pack"]}},{"name":"active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/prices/{id}":{"get":{"operationId":"retrievePrice","summary":"Retrieve a price","tags":["Prices"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updatePrice","summary":"Update a price","description":"Nickname, active, refund terms (`refunds` replaces them whole; what you leave out takes its default) and metadata. Amounts and the model never change.","tags":["Prices"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]},"active":{"type":"boolean"},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"description":"Null or absent: no limit.","anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"network_fee_payer":{"description":"`buyer` (default): the network fee comes out of the refund. `merchant`: you pay it.","type":"string","enum":["buyer","merchant"]}},"required":["allowed"],"additionalProperties":false,"description":"Refund terms the buyer accepts at checkout."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/customers":{"post":{"operationId":"createCustomer","summary":"Create a customer","tags":["Customers"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","minLength":1,"maxLength":120},"external_id":{"description":"Your own id for this buyer (unique).","type":"string","minLength":1,"maxLength":120},"country":{"description":"ISO 3166-1 alpha-2.","type":"string","pattern":"^[A-Z]{2}$"},"locale":{"type":"string","pattern":"^[a-z]{2}$"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listCustomers","summary":"List customers","tags":["Customers"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"email","in":"query","required":false,"schema":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/customers/{id}":{"get":{"operationId":"retrieveCustomer","summary":"Retrieve a customer","tags":["Customers"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateCustomer","summary":"Update a customer","tags":["Customers"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"external_id":{"description":"Your own id for this buyer (unique).","type":"string","minLength":1,"maxLength":120},"country":{"description":"ISO 3166-1 alpha-2.","type":"string","pattern":"^[A-Z]{2}$"},"locale":{"type":"string","pattern":"^[a-z]{2}$"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions":{"post":{"operationId":"createSubscription","summary":"Create a subscription","description":"Renewed by invoice: the customer pays each period themselves. Without a trial the first invoice opens now (`latest_invoice`); the subscription turns active when it is paid.","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"description":"A customer id, `cus_…`.","type":"string","maxLength":80},"price":{"description":"A subscription price.","type":"string","maxLength":80},"quantity":{"type":"integer","minimum":1,"maximum":1000},"coupon":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,40}$"},"trial_days":{"description":"Default: the price's.","type":"integer","minimum":0,"maximum":365},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"required":["customer","price"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listSubscriptions","summary":"List subscriptions","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["trialing","active","past_due","unpaid","paused","canceled","ended"]}},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"price","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A price id, `price_…`."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions/{id}":{"get":{"operationId":"retrieveSubscription","summary":"Retrieve a subscription","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateSubscription","summary":"Update a subscription","description":"`price`: change plan — an upgrade applies now (prorated), a downgrade at the period end (`pending_price`). `cancel_at_period_end`: stop renewing, or take that back.","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price":{"description":"A price id, `price_…`.","type":"string","maxLength":80},"cancel_at_period_end":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions/{id}/cancel":{"post":{"operationId":"cancelSubscription","summary":"Cancel a subscription","description":"Now, or with `at_period_end: true` when the paid period runs out.","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"at_period_end":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions/{id}/pause":{"post":{"operationId":"pauseSubscription","summary":"Pause a subscription","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions/{id}/resume":{"post":{"operationId":"resumeSubscription","summary":"Resume a paused subscription","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/subscriptions/{id}/prepay":{"post":{"operationId":"prepaySubscription","summary":"Invoice several periods ahead","description":"Opens one invoice for `periods` periods (up to the price's `prepay_max_periods`); paying it moves the period on.","tags":["Subscriptions"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"integer","minimum":1,"maximum":36}},"required":["periods"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/payment_links":{"post":{"operationId":"createPaymentLink","summary":"Create a payment link","description":"A page at /l/<slug> that sells one price. Share it anywhere, or open it with pay.js.","tags":["Payment links"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price":{"description":"A price id, `price_…`.","type":"string","maxLength":80},"quantity":{"type":"integer","minimum":1,"maximum":1000},"adjustable_quantity":{"type":"boolean"},"allow_coupons":{"type":"boolean"},"collect_name":{"type":"boolean"},"success_url":{"description":"Where the buyer goes after paying.","type":"string","maxLength":2000,"format":"uri"},"slug":{"description":"Default: random.","type":"string","pattern":"^[A-Za-z0-9_-]{6,64}$"},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"required":["price"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listPaymentLinks","summary":"List payment links","tags":["Payment links"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"price","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A price id, `price_…`."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/payment_links/{id}":{"get":{"operationId":"retrievePaymentLink","summary":"Retrieve a payment link","tags":["Payment links"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updatePaymentLink","summary":"Update a payment link","tags":["Payment links"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"quantity":{"type":"integer","minimum":1,"maximum":1000},"adjustable_quantity":{"type":"boolean"},"allow_coupons":{"type":"boolean"},"collect_name":{"type":"boolean"},"success_url":{"anyOf":[{"type":"string","maxLength":2000,"format":"uri","description":"An http(s) URL."},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key–value pairs (≤ 50 keys, values ≤ 500 characters). On an update they are merged in; an empty value removes its key."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/coupons":{"post":{"operationId":"createCoupon","summary":"Create a coupon","description":"Give `percent_off`, or `amount_off` with its `currency`.","tags":["Coupons"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,40}$","description":"What the buyer types. Case does not matter."},"percent_off":{"type":"integer","minimum":1,"maximum":100},"amount_off":{"type":"integer","minimum":1,"maximum":100000000000,"description":"Amount off in minor units (cents), an integer."},"currency":{"type":"string","enum":["USD","EUR"],"description":"USD or EUR."},"duration":{"description":"For subscriptions: once (default), repeating, forever.","type":"string","enum":["once","repeating","forever"]},"duration_periods":{"description":"With duration `repeating`.","type":"integer","minimum":1,"maximum":120},"max_redemptions":{"type":"integer","minimum":1,"maximum":9007199254740991},"products":{"description":"Only these products. Empty: every product.","maxItems":100,"type":"array","items":{"description":"A product id, `prod_…`.","type":"string","maxLength":80}},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["code"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coupon"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listCoupons","summary":"List coupons","tags":["Coupons"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"code","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,40}$"}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/coupons/{id}":{"get":{"operationId":"retrieveCoupon","summary":"Retrieve a coupon","tags":["Coupons"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coupon"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateCoupon","summary":"Update a coupon","description":"Turn it off, move its end, or change how many may use it. What it takes off never changes.","tags":["Coupons"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"max_redemptions":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coupon"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/entitlements/check":{"get":{"operationId":"checkEntitlement","summary":"Check access","description":"One call: may this customer use this product now? Name the customer by `customer`, `customer_email` or `customer_external_id`, and the product by `product` (or `price`).","tags":["Entitlements"],"security":[{"secretKey":[]}],"parameters":[{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"customer_email","in":"query","required":false,"schema":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},{"name":"customer_external_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."},{"name":"price","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A price id, `price_…`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementCheck"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/entitlements":{"get":{"operationId":"listEntitlements","summary":"List entitlements","tags":["Entitlements"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."},{"name":"subscription","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A subscription id, `sub_…`."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/entitlements/{id}":{"get":{"operationId":"retrieveEntitlement","summary":"Retrieve an entitlement","tags":["Entitlements"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/entitlements/{id}/consume":{"post":{"operationId":"consumeEntitlementCredits","summary":"Spend credits","description":"Spends credits from one credit pack, atomically. Refused when fewer are left. `action` labels the spend for your reports; with an `Idempotency-Key` a retry never spends twice. To spend from a customer's packs together, use POST /credits/consume.","tags":["Entitlements"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","minimum":1,"maximum":1000000},"action":{"description":"Your label for what the credits paid for.","type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$"}},"required":["credits"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/credits/balance":{"get":{"operationId":"retrieveCreditBalance","summary":"Retrieve a credit balance","description":"What a customer has left to spend — on one product's credit packs (`product`), or on all of them — with the buyer's own `top_up_url`: a stable page where they choose a pack and pay. Show it, or send it when `low`.","tags":["Credits"],"security":[{"secretKey":[]}],"parameters":[{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"customer_email","in":"query","required":false,"schema":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},{"name":"customer_external_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalance"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/credits/consume":{"post":{"operationId":"consumeCredits","summary":"Spend credits","description":"Spends `credits` from the customer's packs — of `product`, or of any — oldest first, atomically, never below zero. Refused with `insufficient_credits` (409) when fewer are left; nothing is spent then. Send an `Idempotency-Key`: a retry with it returns the first spend and never spends twice, however late it comes. Crossing the product's low-balance threshold sends `credits.low`; reaching zero, `credits.depleted`.","tags":["Credits"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"description":"A customer id, `cus_…`.","type":"string","maxLength":80},"customer_email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"customer_external_id":{"type":"string","minLength":1,"maxLength":120},"credits":{"type":"integer","minimum":1,"maximum":1000000},"product":{"description":"A product id, `prod_…`.","type":"string","maxLength":80},"action":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$","description":"Your label for what the credits paid for (`chat`, `image.hd`, `api/search`). Shows in your dashboard by action."}},"required":["credits"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/credits/usage":{"get":{"operationId":"listCreditUsage","summary":"List credit spends","tags":["Credits"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."},{"name":"action","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$"},"description":"Your label for what the credits paid for (`chat`, `image.hd`, `api/search`). Shows in your dashboard by action."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CreditUsage"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys/validate":{"post":{"operationId":"validateLicenseKey","summary":"Validate a license key","description":"Public: call it from your app with the license key alone. With `instance` (an activation id) or `instance_name`, also checks that this instance is activated.","tags":["License keys"],"security":[{},{"secretKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"XXXXX-XXXXX-XXXXX-XXXXX","type":"string","maxLength":40},"product":{"description":"Refuse a key for any other product. Recommended.","type":"string","maxLength":80},"merchant":{"description":"Your account's slug. Only needed if two accounts ever share a key (practically never).","type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"},"instance":{"description":"An activation id, `act_…`.","type":"string","maxLength":80},"instance_name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the machine or site, e.g. a hostname."}},"required":["key"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseCheck"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys/activate":{"post":{"operationId":"activateLicenseKey","summary":"Activate a license key on an instance","description":"Public. Activating the same `instance_name` again returns its activation. Refused (`limit_reached`) when the key is active on as many instances as it allows.","tags":["License keys"],"security":[{},{"secretKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"XXXXX-XXXXX-XXXXX-XXXXX","type":"string","maxLength":40},"product":{"description":"Refuse a key for any other product. Recommended.","type":"string","maxLength":80},"merchant":{"description":"Your account's slug. Only needed if two accounts ever share a key (practically never).","type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"},"instance_name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the machine or site, e.g. a hostname."}},"required":["key","instance_name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseCheck"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys/deactivate":{"post":{"operationId":"deactivateLicenseKey","summary":"Deactivate a license key on an instance","description":"Public. Frees a seat: give the activation id (`instance`) or the `instance_name`.","tags":["License keys"],"security":[{},{"secretKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"XXXXX-XXXXX-XXXXX-XXXXX","type":"string","maxLength":40},"product":{"description":"Refuse a key for any other product. Recommended.","type":"string","maxLength":80},"merchant":{"description":"Your account's slug. Only needed if two accounts ever share a key (practically never).","type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"},"instance":{"type":"string","maxLength":80},"instance_name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the machine or site, e.g. a hostname."}},"required":["key"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseCheck"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys":{"get":{"operationId":"listLicenseKeys","summary":"List license keys","tags":["License keys"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"customer","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A customer id, `cus_…`."},{"name":"product","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A product id, `prod_…`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","suspended","revoked","expired"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/LicenseKey"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys/{id}":{"get":{"operationId":"retrieveLicenseKey","summary":"Retrieve a license key","tags":["License keys"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseKey"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/license_keys/{id}/revoke":{"post":{"operationId":"revokeLicenseKey","summary":"Revoke a license key","description":"For good: validation answers `revoked` from now on.","tags":["License keys"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseKey"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/portal_sessions":{"post":{"operationId":"createPortalSession","summary":"Create a buyer-portal link","description":"A one-hour link where your customer sees their subscriptions, receipts and license keys. Make one when they click \"Billing\" in your app and redirect them to `url`.","tags":["Buyer portal"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"description":"A customer id, `cus_…`.","type":"string","maxLength":80},"return_url":{"description":"Where \"Back\" goes.","type":"string","maxLength":2000,"format":"uri"}},"required":["customer"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalSession"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/payments":{"get":{"operationId":"listPayments","summary":"List payments","description":"Transfers seen on chain into addresses we handed out, newest first.","tags":["Payments"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"invoice","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A invoice id, `inv_…`."},{"name":"asset","in":"query","required":false,"schema":{"type":"string","enum":["BTC","USDC","USDT"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/payments/{id}":{"get":{"operationId":"retrievePayment","summary":"Retrieve a payment","tags":["Payments"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/refunds/quote":{"get":{"operationId":"quoteRefund","summary":"Quote a refund","description":"What a refund of this invoice would be now: the amount left, today's network fee, what you would send.","tags":["Refunds"],"security":[{"secretKey":[]}],"parameters":[{"name":"invoice","in":"query","required":true,"schema":{"type":"string","maxLength":80},"description":"A invoice id, `inv_…`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundQuote"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/refunds":{"post":{"operationId":"createRefund","summary":"Open a refund","description":"Starts a refund in the asset that was paid. We email the buyer a link to give an address; the link is never returned, since whoever holds it decides where the money goes. With no email on the invoice, the owner makes one in the dashboard. When the address is checked, the refund is `ready_to_send` with `amount_to_send`. Refused with `sanctioned_sender` when money on the invoice came from an address on a sanctions list, or one the coin's issuer froze: sending it back may itself be prohibited, so nothing refunds it — leave it and talk to a lawyer.","tags":["Refunds"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"description":"A invoice id, `inv_…`.","type":"string","maxLength":80},"amount":{"description":"In the paid asset's smallest unit. Default: everything still refundable.","type":"string","pattern":"^[1-9][0-9]{0,77}$"},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["invoice"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listRefunds","summary":"List refunds","tags":["Refunds"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"invoice","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A invoice id, `inv_…`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["requested","awaiting_address","ready_to_send","sent","confirmed","canceled"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/refunds/{id}":{"get":{"operationId":"retrieveRefund","summary":"Retrieve a refund","tags":["Refunds"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/refunds/{id}/mark_sent":{"post":{"operationId":"markRefundSent","summary":"Record the refund's transaction","description":"After you sent `amount_to_send` to `refund_address`. We read that transaction on the network: it must pay the refund address the amount to send. Then the refund is `sent` (or `confirmed`, with its receipt, when already deep). This is the only way a refund moves on: a transfer we merely see at the address may be someone else's, so it never counts by itself.","tags":["Refunds"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]{64}$","description":"The transaction hash."}},"required":["txid"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/receipts":{"get":{"operationId":"listReceipts","summary":"List receipts","description":"One for every fulfilled payment and every confirmed refund, newest first.","tags":["Receipts"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"invoice","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"A invoice id, `inv_…`."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["payment","refund"]}}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Receipt"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/receipts/{id}":{"get":{"operationId":"retrieveReceipt","summary":"Retrieve a receipt","tags":["Receipts"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/receipts/{id}/pdf":{"get":{"operationId":"receiptPdf","summary":"Download a receipt as PDF","tags":["Receipts"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"The file.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/events":{"get":{"operationId":"listEvents","summary":"List events","description":"What happened in the last 30 days, newest first. `type` filters (`invoice.paid`, or `invoice.*`).","tags":["Events"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."},{"name":"type","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z_]+\\.([a-z_.]+|\\*)$"}},{"name":"object","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Only events about this object (`inv_…`, `sub_…`)."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/events/{id}":{"get":{"operationId":"retrieveEvent","summary":"Retrieve an event","tags":["Events"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/webhook_endpoints":{"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"The response carries `secret` — the only time you see it. Keep it to verify `Perly-Signature`.","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000},"enabled_events":{"minItems":1,"maxItems":47,"type":"array","items":{"anyOf":[{"type":"string","const":"*"},{"type":"string","enum":["invoice.created","invoice.rail_chosen","invoice.open","invoice.seen","invoice.underpaid","invoice.paid","invoice.overpaid","invoice.review","invoice.expired","invoice.canceled","invoice.fulfilled","invoice.refunded","invoice.sent","invoice.found_on_other_network","payment.received","payment.confirmed","payment.dropped","receipt.created","refund.requested","refund.address_received","refund.sent","refund.confirmed","refund.canceled","subscription.created","subscription.activated","subscription.trial_ending","subscription.renewal_invoice_opened","subscription.renewed","subscription.past_due","subscription.unpaid","subscription.paused","subscription.resumed","subscription.plan_changed","subscription.canceled","subscription.ended","entitlement.granted","entitlement.revoked","credits.low","credits.depleted","checkout.completed","license.created","license.revoked","customer.created","webhook_endpoint.disabled","webhook.test","plan.changed"]}]},"description":"Event types to send, or `[\"*\"]` for every one."},"description":{"type":"string","minLength":1,"maxLength":200}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"How many objects to return, 1–100. Default 10."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":300},"description":"`next_cursor` from the previous page."}],"responses":{"200":{"description":"A page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/webhook_endpoints/{id}":{"get":{"operationId":"retrieveWebhookEndpoint","summary":"Retrieve a webhook endpoint","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateWebhookEndpoint","summary":"Update a webhook endpoint","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000},"enabled_events":{"minItems":1,"maxItems":47,"type":"array","items":{"anyOf":[{"type":"string","const":"*"},{"type":"string","enum":["invoice.created","invoice.rail_chosen","invoice.open","invoice.seen","invoice.underpaid","invoice.paid","invoice.overpaid","invoice.review","invoice.expired","invoice.canceled","invoice.fulfilled","invoice.refunded","invoice.sent","invoice.found_on_other_network","payment.received","payment.confirmed","payment.dropped","receipt.created","refund.requested","refund.address_received","refund.sent","refund.confirmed","refund.canceled","subscription.created","subscription.activated","subscription.trial_ending","subscription.renewal_invoice_opened","subscription.renewed","subscription.past_due","subscription.unpaid","subscription.paused","subscription.resumed","subscription.plan_changed","subscription.canceled","subscription.ended","entitlement.granted","entitlement.revoked","credits.low","credits.depleted","checkout.completed","license.created","license.revoked","customer.created","webhook_endpoint.disabled","webhook.test","plan.changed"]}]},"description":"Event types to send, or `[\"*\"]` for every one."},"description":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"disabled":{"description":"Stop sending without deleting it.","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/webhook_endpoints/{id}/roll_secret":{"post":{"operationId":"rollWebhookSecret","summary":"Roll the signing secret","description":"A new secret from now on; the old one stops at once. The response carries the new `secret`.","tags":["Webhook endpoints"],"security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"webhooks":{"event":{"post":{"summary":"An event, signed","description":"We POST each event to your endpoints with `Perly-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>`. Verify it on the raw body and refuse anything older than 300 seconds (`perly-pay`: `webhooks.verify`). Answer 2xx quickly; we retry with backoff otherwise.","parameters":[{"name":"Perly-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received."}}}}},"components":{"securitySchemes":{"secretKey":{"type":"http","scheme":"bearer","description":"Your secret key, sk_test_… or sk_live_…. Never put it in a browser or an app."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (a UUID). A retry with the same key returns the first response for 24 hours.","schema":{"type":"string","maxLength":255}}},"responses":{"Error":{"description":"An error: 400 invalid, 401 no or bad key, 403 not allowed, 404 missing, 409 conflict, 429 slow down, 5xx ours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Customer":{"type":"object","properties":{"id":{"type":"string","description":"`cus_…`"},"object":{"type":"string","const":"customer"},"livemode":{"type":"boolean"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"external_id":{"description":"Your own id for this buyer.","type":["string","null"]},"country":{"type":["string","null"]},"locale":{"type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","email","name","external_id","country","locale","metadata","created"],"additionalProperties":false},"Product":{"type":"object","properties":{"id":{"type":"string","description":"`prod_…`"},"object":{"type":"string","const":"product"},"livemode":{"type":"boolean"},"name":{"type":"string"},"description":{"type":["string","null"]},"image_url":{"type":["string","null"]},"issues_license":{"type":"boolean"},"license_activation_limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"active":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"},"updated":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","name","description","image_url","issues_license","license_activation_limit","active","metadata","created","updated"],"additionalProperties":false},"Price":{"type":"object","properties":{"id":{"type":"string","description":"`price_…`"},"object":{"type":"string","const":"price"},"livemode":{"type":"boolean"},"product":{"type":"string","description":"`prod_…`"},"model":{"type":"string","enum":["one_time","pay_what_you_want","fixed_term","subscription","lifetime","credit_pack"]},"currency":{"type":"string","enum":["USD","EUR"]},"nickname":{"type":["string","null"]},"active":{"type":"boolean"},"unit_amount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},{"type":"null"}],"description":"Null for pay-what-you-want and tiered lifetime prices."},"custom_amount":{"anyOf":[{"type":"object","properties":{"minimum":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"suggested":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},{"type":"null"}]}},"required":["minimum","suggested"],"additionalProperties":false},{"type":"null"}]},"term_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"recurring":{"anyOf":[{"type":"object","properties":{"interval":{"type":"string","enum":["day","week","month","quarter","year","custom_days"]},"interval_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"trial_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"grace_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"prepay_max_periods":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"keep_renewal_price":{"type":"boolean"}},"required":["interval","interval_days","trial_days","grace_days","prepay_max_periods","keep_renewal_price"],"additionalProperties":false},{"type":"null"}]},"lifetime":{"anyOf":[{"type":"object","properties":{"quantity_cap":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"`tier_…`"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"seats":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."}},"required":["id","position","name","seats","unit_amount"],"additionalProperties":false}}},"required":["quantity_cap","tiers"],"additionalProperties":false},{"type":"null"}]},"credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"refunds":{"type":"object","properties":{"allowed":{"type":"boolean"},"window_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"network_fee_payer":{"type":"string","enum":["buyer","merchant"]}},"required":["allowed","window_days","network_fee_payer"],"additionalProperties":false},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","product","model","currency","nickname","active","unit_amount","custom_amount","term_days","recurring","lifetime","credits","refunds","metadata","created"],"additionalProperties":false},"Coupon":{"type":"object","properties":{"id":{"type":"string","description":"`cpn_…`"},"object":{"type":"string","const":"coupon"},"livemode":{"type":"boolean"},"code":{"type":"string"},"percent_off":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amount_off":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","enum":["USD","EUR"]},{"type":"null"}]},"duration":{"type":"string","enum":["once","repeating","forever"]},"duration_periods":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"max_redemptions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"times_redeemed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"products":{"type":"array","items":{"type":"string","description":"`prod_…`"},"description":"Empty means every product."},"expires_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"active":{"type":"boolean"},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","code","percent_off","amount_off","currency","duration","duration_periods","max_redemptions","times_redeemed","products","expires_at","active","created"],"additionalProperties":false},"PaymentLink":{"type":"object","properties":{"id":{"type":"string","description":"`plink_…`"},"object":{"type":"string","const":"payment_link"},"livemode":{"type":"boolean"},"url":{"type":"string"},"slug":{"type":"string"},"price":{"type":"string","description":"`price_…`"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"adjustable_quantity":{"type":"boolean"},"allow_coupons":{"type":"boolean"},"collect_name":{"type":"boolean"},"success_url":{"type":["string","null"]},"active":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","url","slug","price","quantity","adjustable_quantity","allow_coupons","collect_name","success_url","active","metadata","created"],"additionalProperties":false},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string","description":"`cs_…`"},"object":{"type":"string","const":"checkout_session"},"livemode":{"type":"boolean"},"url":{"type":"string","description":"Send the buyer here, or open it with pay.js."},"status":{"type":"string","enum":["open","complete","expired"]},"currency":{"type":"string","enum":["USD","EUR"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"`csl_…`"},"price":{"type":"string","description":"`price_…`"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"custom_amount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},{"type":"null"}]},"unit_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."}},"required":["id","price","quantity","custom_amount","unit_amount","amount"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"discount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"customer_email":{"type":["string","null"]},"coupon":{"anyOf":[{"type":"string","description":"`cpn_…`"},{"type":"null"}]},"payment_link":{"anyOf":[{"type":"string","description":"`plink_…`"},{"type":"null"}]},"return_url":{"type":["string","null"]},"cancel_url":{"type":["string","null"]},"invoice":{"anyOf":[{"type":"string","description":"`inv_…`"},{"type":"null"}]},"expires_at":{"type":"string","description":"ISO 8601"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","url","status","currency","line_items","subtotal","discount","total","customer","customer_email","coupon","payment_link","return_url","cancel_url","invoice","expires_at","metadata","created"],"additionalProperties":false},"Invoice":{"type":"object","properties":{"id":{"type":"string","description":"`inv_…`"},"object":{"type":"string","const":"invoice"},"livemode":{"type":"boolean"},"url":{"type":"string","description":"The buyer's payment page."},"status":{"type":"string","enum":["open","seen","underpaid","paid","overpaid","review","expired","canceled","refunded","partially_refunded"]},"kind":{"type":"string","enum":["checkout","payment_link","subscription","manual","api","plan"]},"number":{"type":["string","null"]},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"customer_email":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"description":{"type":["string","null"]},"currency":{"type":"string","enum":["USD","EUR"]},"subtotal":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"discount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"total_usd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What is settled, in US cents, locked when the invoice opened."},"received_usd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"pending_usd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"amount_received":{"type":"string","description":"Integer string in the asset's smallest unit."},"payment":{"anyOf":[{"type":"object","properties":{"chain":{"type":"string"},"asset":{"type":"string","enum":["BTC","USDC","USDT"],"description":"`BTC`, `USDC` or `USDT`. On `arbitrum` and `optimism`, `USDT` is USDT0 (LayerZero's omnichain USDT); show it as USDT0 there."},"address":{"type":"string"},"amount_due":{"type":"string","description":"Integer string in the asset's smallest unit."},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"btc_usd_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"opened_at":{"type":"string","description":"ISO 8601"},"expires_at":{"type":"string","description":"ISO 8601"}},"required":["chain","asset","address","amount_due","decimals","btc_usd_cents","opened_at","expires_at"],"additionalProperties":false},{"type":"null"}],"description":"The chain and asset the buyer chose; null until then."},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"`il_…`"},"price":{"anyOf":[{"type":"string","description":"`price_…`"},{"type":"null"}]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"description":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"period_start":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"period_end":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]}},"required":["id","price","product","description","quantity","unit_amount","amount","period_start","period_end"],"additionalProperties":false}},"subscription":{"anyOf":[{"type":"string","description":"`sub_…`"},{"type":"null"}]},"checkout_session":{"anyOf":[{"type":"string","description":"`cs_…`"},{"type":"null"}]},"payment_link":{"anyOf":[{"type":"string","description":"`plink_…`"},{"type":"null"}]},"coupon":{"anyOf":[{"type":"string","description":"`cpn_…`"},{"type":"null"}]},"receipt_number":{"type":["string","null"]},"review_reason":{"type":["string","null"]},"due_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"paid_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"fulfilled_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"canceled_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","url","status","kind","number","customer","customer_email","customer_name","description","currency","subtotal","discount","total","total_usd","received_usd","pending_usd","amount_received","payment","lines","subscription","checkout_session","payment_link","coupon","receipt_number","review_reason","due_at","paid_at","fulfilled_at","canceled_at","metadata","created"],"additionalProperties":false},"Subscription":{"type":"object","properties":{"id":{"type":"string","description":"`sub_…`"},"object":{"type":"string","const":"subscription"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["trialing","active","past_due","unpaid","paused","canceled","ended"]},"customer":{"type":"string","description":"`cus_…`"},"price":{"type":"string","description":"`price_…`"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"current_period_start":{"type":"string","description":"ISO 8601"},"current_period_end":{"type":"string","description":"ISO 8601"},"trial_end":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"grace_days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cancel_at_period_end":{"type":"boolean"},"canceled_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"paused_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"pending_price":{"anyOf":[{"type":"string","description":"`price_…`"},{"type":"null"}],"description":"A downgrade waiting for the period end."},"kept_price":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},{"type":"null"}],"description":"The renewal price this subscriber keeps."},"latest_invoice":{"anyOf":[{"type":"string","description":"`inv_…`"},{"type":"null"}]},"coupon":{"anyOf":[{"type":"string","description":"`cpn_…`"},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","status","customer","price","quantity","current_period_start","current_period_end","trial_end","grace_days","cancel_at_period_end","canceled_at","ended_at","paused_at","pending_price","kept_price","latest_invoice","coupon","metadata","created"],"additionalProperties":false},"Entitlement":{"type":"object","properties":{"id":{"type":"string","description":"`ent_…`"},"object":{"type":"string","const":"entitlement"},"livemode":{"type":"boolean"},"active":{"type":"boolean","description":"Started, not ended, not revoked."},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"price":{"anyOf":[{"type":"string","description":"`price_…`"},{"type":"null"}]},"model":{"type":"string","enum":["one_time","pay_what_you_want","fixed_term","subscription","lifetime","credit_pack"]},"subscription":{"anyOf":[{"type":"string","description":"`sub_…`"},{"type":"null"}]},"invoice":{"type":"string","description":"`inv_…`"},"starts_at":{"type":"string","description":"ISO 8601"},"ends_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}],"description":"Null = for ever."},"credits_total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"credits_used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credits_remaining":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"tier":{"anyOf":[{"type":"string","description":"`tier_…`"},{"type":"null"}]},"seat_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","active","customer","product","price","model","subscription","invoice","starts_at","ends_at","credits_total","credits_used","credits_remaining","tier","seat_number","revoked_at","created"],"additionalProperties":false},"EntitlementCheck":{"type":"object","properties":{"object":{"type":"string","const":"entitlement_check"},"has_access":{"type":"boolean"},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"ends_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}],"description":"The latest end among active entitlements; null = for ever (or none)."},"credits_remaining":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"entitlements":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}},"required":["object","has_access","customer","product","ends_at","credits_remaining","entitlements"],"additionalProperties":false},"CreditBalance":{"type":"object","properties":{"object":{"type":"string","const":"credit_balance"},"livemode":{"type":"boolean"},"customer":{"type":"string","description":"`cus_…`"},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}],"description":"Null = every product's credits together."},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits left on active packs."},"low_balance_threshold":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The product's threshold; null = none set."},"low":{"type":"boolean","description":"At or under the threshold (or zero)."},"top_up_url":{"type":"string","description":"The buyer's own top-up page: stable, safe to email or show in your app."}},"required":["object","livemode","customer","product","balance","low_balance_threshold","low","top_up_url"],"additionalProperties":false},"CreditUsage":{"type":"object","properties":{"id":{"type":"string","description":"`cu_…`"},"object":{"type":"string","const":"credit_usage"},"livemode":{"type":"boolean"},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"entitlement":{"anyOf":[{"type":"string","description":"`ent_…`"},{"type":"null"}],"description":"Set when one pack was named."},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"action":{"description":"Your label for what was done (`chat`, `image.hd`, …).","type":["string","null"]},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What was left right after."},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","customer","product","entitlement","credits","action","balance","created"],"additionalProperties":false},"LicenseKey":{"type":"object","properties":{"id":{"type":"string","description":"`lic_…`"},"object":{"type":"string","const":"license_key"},"livemode":{"type":"boolean"},"key":{"type":"string"},"status":{"type":"string","enum":["active","suspended","revoked","expired"]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"customer":{"anyOf":[{"type":"string","description":"`cus_…`"},{"type":"null"}]},"entitlement":{"type":"string","description":"`ent_…`"},"activation_limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"activations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","key","status","product","customer","entitlement","activation_limit","activations","expires_at","created"],"additionalProperties":false},"LicenseCheck":{"type":"object","properties":{"object":{"type":"string","const":"license_check"},"valid":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["not_found","wrong_product","suspended","revoked","expired","limit_reached","not_activated"]},{"type":"null"}]},"license_key":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"livemode":{"type":"boolean"},"status":{"type":"string","enum":["active","suspended","revoked","expired"]},"product":{"anyOf":[{"type":"string","description":"`prod_…`"},{"type":"null"}]},"activation_limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"activations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expires_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]}},"required":["key","livemode","status","product","activation_limit","activations","expires_at"],"additionalProperties":false},{"type":"null"}]},"activation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"`act_…`"},"instance_name":{"type":"string"},"active":{"type":"boolean"},"created":{"type":"string","description":"ISO 8601"}},"required":["id","instance_name","active","created"],"additionalProperties":false},{"type":"null"}]}},"required":["object","valid","reason","license_key","activation"],"additionalProperties":false},"PortalSession":{"type":"object","properties":{"id":{"type":"string","description":"`bps_…`"},"object":{"type":"string","const":"portal_session"},"livemode":{"type":"boolean"},"customer":{"type":"string","description":"`cus_…`"},"url":{"type":"string","description":"Shown once. Valid until expires_at."},"return_url":{"type":["string","null"]},"expires_at":{"type":"string","description":"ISO 8601"},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","customer","url","return_url","expires_at","created"],"additionalProperties":false},"Payment":{"type":"object","properties":{"id":{"type":"string","description":"`pay_…`"},"object":{"type":"string","const":"payment"},"livemode":{"type":"boolean"},"invoice":{"anyOf":[{"type":"string","description":"`inv_…`"},{"type":"null"}]},"chain":{"type":"string"},"asset":{"type":"string","enum":["BTC","USDC","USDT"],"description":"`BTC`, `USDC` or `USDT`. On `arbitrum` and `optimism`, `USDT` is USDT0 (LayerZero's omnichain USDT); show it as USDT0 there."},"token":{"type":["string","null"]},"txid":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"Integer string in the asset's smallest unit."},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usd_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"from_address":{"type":["string","null"]},"to_address":{"type":"string"},"block_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"confirmations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"arrived_at":{"type":"string","description":"ISO 8601"},"confirmed_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"dropped_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","invoice","chain","asset","token","txid","position","amount","decimals","usd_cents","from_address","to_address","block_number","confirmations","arrived_at","confirmed_at","dropped_at","created"],"additionalProperties":false},"Refund":{"type":"object","properties":{"id":{"type":"string","description":"`re_…`"},"object":{"type":"string","const":"refund"},"livemode":{"type":"boolean"},"invoice":{"type":"string","description":"`inv_…`"},"payment":{"anyOf":[{"type":"string","description":"`pay_…`"},{"type":"null"}]},"status":{"type":"string","enum":["requested","awaiting_address","ready_to_send","sent","confirmed","canceled"]},"chain":{"type":"string"},"asset":{"type":"string","enum":["BTC","USDC","USDT"],"description":"`BTC`, `USDC` or `USDT`. On `arbitrum` and `optimism`, `USDT` is USDT0 (LayerZero's omnichain USDT); show it as USDT0 there."},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"Integer string in the asset's smallest unit."},"network_fee":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}]},"network_fee_payer":{"type":"string","enum":["buyer","merchant"]},"amount_to_send":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}]},"reason":{"type":["string","null"]},"refund_address":{"type":["string","null"]},"txid":{"description":"The transaction you named with mark_sent. Only it confirms the refund.","type":["string","null"]},"sent_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"confirmed_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"canceled_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","invoice","payment","status","chain","asset","decimals","amount","network_fee","network_fee_payer","amount_to_send","reason","refund_address","txid","sent_at","confirmed_at","canceled_at","created"],"additionalProperties":false},"RefundQuote":{"type":"object","properties":{"object":{"type":"string","const":"refund_quote"},"invoice":{"type":"string","description":"`inv_…`"},"refundable":{"type":"boolean"},"reason":{"type":["string","null"]},"chain":{"type":["string","null"]},"asset":{"anyOf":[{"type":"string","enum":["BTC","USDC","USDT"],"description":"`BTC`, `USDC` or `USDT`. On `arbitrum` and `optimism`, `USDT` is USDT0 (LayerZero's omnichain USDT); show it as USDT0 there."},{"type":"null"}]},"decimals":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amount":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}],"description":"What can still be refunded."},"network_fee":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}]},"network_fee_payer":{"anyOf":[{"type":"string","enum":["buyer","merchant"]},{"type":"null"}]},"amount_to_send":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}]}},"required":["object","invoice","refundable","reason","chain","asset","decimals","amount","network_fee","network_fee_payer","amount_to_send"],"additionalProperties":false},"Receipt":{"type":"object","properties":{"id":{"type":"string","description":"`rcpt_…`"},"object":{"type":"string","const":"receipt"},"livemode":{"type":"boolean"},"kind":{"type":"string","enum":["payment","refund"]},"number":{"type":"string"},"invoice":{"type":"string","description":"`inv_…`"},"refund":{"anyOf":[{"type":"string","description":"`re_…`"},{"type":"null"}]},"url":{"type":"string","description":"The public receipt page."},"pdf":{"type":"string","description":"This API's PDF of it."},"customer_email":{"type":["string","null"]},"currency":{"type":"string","enum":["USD","EUR"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)."},"asset":{"anyOf":[{"type":"string","enum":["BTC","USDC","USDT"],"description":"`BTC`, `USDC` or `USDT`. On `arbitrum` and `optimism`, `USDT` is USDT0 (LayerZero's omnichain USDT); show it as USDT0 there."},{"type":"null"}]},"asset_amount":{"anyOf":[{"type":"string","description":"Integer string in the asset's smallest unit."},{"type":"null"}]},"decimals":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"type":"string","description":"ISO 8601"},"emailed_at":{"anyOf":[{"type":"string","description":"ISO 8601"},{"type":"null"}]}},"required":["id","object","livemode","kind","number","invoice","refund","url","pdf","customer_email","currency","amount","asset","asset_amount","decimals","issued_at","emailed_at"],"additionalProperties":false},"Event":{"type":"object","properties":{"id":{"type":"string","description":"`evt_…`"},"object":{"type":"string","const":"event"},"livemode":{"type":"boolean"},"type":{"type":"string","description":"`<object>.<verb>`, e.g. invoice.paid."},"object_type":{"type":"string"},"object_id":{"type":["string","null"]},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"`object`: the object the event is about, as the API shows it now; plus what the event recorded."},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","type","object_type","object_id","data","created"],"additionalProperties":false},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","description":"`we_…`"},"object":{"type":"string","const":"webhook_endpoint"},"livemode":{"type":"boolean"},"url":{"type":"string"},"description":{"type":["string","null"]},"enabled_events":{"type":"array","items":{"type":"string"},"description":"`*` is every event."},"status":{"type":"string","enum":["enabled","disabled"]},"secret_prefix":{"type":"string"},"secret":{"description":"The signing secret, `whsec_…`. Only when created or rolled.","type":"string"},"created":{"type":"string","description":"ISO 8601"}},"required":["id","object","livemode","url","description","enabled_events","status","secret_prefix","created"],"additionalProperties":false},"Deleted":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","idempotency_error","api_error"]},"code":{"type":"string","description":"Stable, machine-readable: `parameter_invalid`, `resource_missing`, …"},"message":{"type":"string","description":"One sentence for a person."},"param":{"type":"string","description":"The parameter at fault, e.g. `line_items[0].price`."}}}}}}},"x-event-types":["invoice.created","invoice.rail_chosen","invoice.open","invoice.seen","invoice.underpaid","invoice.paid","invoice.overpaid","invoice.review","invoice.expired","invoice.canceled","invoice.fulfilled","invoice.refunded","invoice.sent","invoice.found_on_other_network","payment.received","payment.confirmed","payment.dropped","receipt.created","refund.requested","refund.address_received","refund.sent","refund.confirmed","refund.canceled","subscription.created","subscription.activated","subscription.trial_ending","subscription.renewal_invoice_opened","subscription.renewed","subscription.past_due","subscription.unpaid","subscription.paused","subscription.resumed","subscription.plan_changed","subscription.canceled","subscription.ended","entitlement.granted","entitlement.revoked","credits.low","credits.depleted","checkout.completed","license.created","license.revoked","customer.created","webhook_endpoint.disabled","webhook.test","plan.changed"]}