{"openapi":"3.1.0","info":{"title":"DEV3 Cyclestrand API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"n3k_…"}}},"paths":{"/me":{"get":{"summary":"The workspace this key belongs to","tags":["Workspace"],"security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products":{"get":{"summary":"List products","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a product","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":2000},"tax_code":{"type":"string","maxLength":40},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products/{id}":{"get":{"summary":"Retrieve a product","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Archive a product","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/prices":{"get":{"summary":"List prices","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a price (flat, per unit, tiered, volume, package or metered)","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"type":"object","properties":{"unit":{"type":"string","enum":["day","week","month","year"]},"count":{"default":1,"type":"integer","minimum":1,"maximum":36}},"required":["unit","count"],"additionalProperties":false},"model":{"type":"string","enum":["flat","per_unit","tiered_graduated","tiered_volume","package","metered_sum","metered_max","metered_last"]},"unit_amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit_size":{"type":"integer","minimum":1,"maximum":9007199254740991},"tiers":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"up_to":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"unit_amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"flat_amount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["up_to","unit_amount"],"additionalProperties":false}},"package_size":{"type":"integer","minimum":1,"maximum":9007199254740991},"metered_pricing":{"type":"string","enum":["per_unit","graduated","volume","package"]},"free_units":{"type":"integer","minimum":0,"maximum":9007199254740991},"trial_days":{"type":"integer","minimum":0,"maximum":730},"tax_behavior":{"type":"string","enum":["inclusive","exclusive"]},"meterId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"nickname":{"type":"string","maxLength":120}},"required":["productId","currency","interval","model"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/prices/{id}":{"get":{"summary":"Retrieve a price","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Archive a price","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/prices/{id}/quote":{"get":{"summary":"What would this price cost for a quantity?","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"quantity","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":1000000000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/coupons":{"get":{"summary":"List coupons","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a coupon","tags":["Catalogue"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":40},"percent_bp":{"type":"integer","minimum":1,"maximum":10000},"amount_off":{"type":"integer","minimum":1,"maximum":9007199254740991},"currency":{"type":"string","minLength":3,"maxLength":3},"duration":{"type":"string","enum":["once","repeating","forever"]},"duration_months":{"type":"integer","minimum":1,"maximum":60},"max_redemptions":{"type":"integer","minimum":1,"maximum":9007199254740991},"expires_at":{},"priceIds":{"type":"array","items":{"type":"string","pattern":"^[0-9a-f]{24}$"}}},"required":["code"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"email","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","maxLength":200,"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","maxLength":160},"external_id":{"type":"string","maxLength":100},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"region":{"type":"string","maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"type":"string","minLength":2,"maxLength":2}},"additionalProperties":false},"tax_id":{"type":"string","maxLength":30},"tax_exempt":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["email"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/customers/{id}":{"get":{"summary":"Retrieve a customer","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","maxLength":200,"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","maxLength":160},"external_id":{"type":"string","maxLength":100},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"region":{"type":"string","maxLength":100},"postal_code":{"type":"string","maxLength":20},"country":{"type":"string","minLength":2,"maxLength":2}},"additionalProperties":false},"tax_id":{"type":"string","maxLength":30},"tax_exempt":{"type":"boolean"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Delete a customer (refused while invoices are open)","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/customers/{id}/payment-methods":{"post":{"summary":"Attach a gateway payment-method token","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"token":{"type":"string","minLength":4,"maxLength":100},"brand":{"type":"string","maxLength":20},"last4":{"type":"string","minLength":4,"maxLength":4},"exp_month":{"type":"integer","minimum":1,"maximum":12},"exp_year":{"type":"integer","minimum":2000,"maximum":2200},"default":{"type":"boolean"}},"required":["token"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"get":{"summary":"List payment methods","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/customers/{id}/default-payment-method":{"post":{"summary":"Set the default payment method","tags":["Customers"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payment_method":{"type":"string","pattern":"^[0-9a-f]{24}$"}},"required":["payment_method"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions":{"get":{"summary":"List subscriptions","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"customerId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a subscription (bills the first period unless trialing)","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"quantity":{"type":"integer","minimum":0,"maximum":1000000},"addon":{"type":"boolean"}},"required":["priceId"],"additionalProperties":false}},"trial_days":{"type":"integer","minimum":0,"maximum":730},"coupon":{"type":"string","maxLength":40},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"]},"proration_behavior":{"type":"string","enum":["create_prorations","always_invoice","none"]},"allow_multiple":{"type":"boolean"}},"required":["customerId","items"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}":{"get":{"summary":"Retrieve a subscription","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Change items or quantities with a proration behaviour, or schedule the change for period end","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"quantity":{"type":"integer","minimum":0,"maximum":1000000},"addon":{"type":"boolean"}},"required":["priceId"],"additionalProperties":false}},"proration_behavior":{"type":"string","enum":["create_prorations","always_invoice","none"]},"schedule_at_period_end":{"type":"boolean"}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}/preview":{"post":{"summary":"Proration preview (nothing is changed or billed)","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"quantity":{"type":"integer","minimum":0,"maximum":1000000},"addon":{"type":"boolean"}},"required":["priceId"],"additionalProperties":false}},"at":{}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}/cancel":{"post":{"summary":"Cancel at period end (default) or immediately","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"at_period_end":{"type":"boolean"},"prorate":{"type":"boolean"},"reason":{"type":"string","maxLength":300}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}/resume":{"post":{"summary":"Undo a pending cancellation or resume a paused subscription","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}/pause":{"post":{"summary":"Pause billing","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/usage":{"post":{"summary":"Record up to 1,000 usage events (idempotent per idempotency_key)","tags":["Usage"],"security":[{"bearer":[]}],"x-scope":"usage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"events":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"event_name":{"type":"string","maxLength":64},"customer":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"timestamp":{},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["event_name","customer","idempotency_key"],"additionalProperties":false}},"strict":{"type":"boolean"}},"required":["events"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices":{"get":{"summary":"List invoices","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"customerId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","open","paid","void","uncollectible"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a one-off draft invoice","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"currency":{"type":"string","minLength":3,"maxLength":3},"lines":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":300},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quantity":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["description","amount"],"additionalProperties":false}},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"]}},"required":["customerId","currency","lines"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}":{"get":{"summary":"Retrieve an invoice","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/finalize":{"post":{"summary":"Finalise a draft (assigns the number; idempotent)","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/pay":{"post":{"summary":"Attempt payment now","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payment_token":{"type":"string","maxLength":100}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/void":{"post":{"summary":"Void an open invoice","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/uncollectible":{"post":{"summary":"Mark an open invoice uncollectible","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/pdf":{"get":{"summary":"Invoice as a PDF","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/credit-notes":{"get":{"summary":"List credit notes","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Issue a credit note against a paid invoice (refund or credit balance)","tags":["Invoices"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invoiceId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"lines":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":300},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["description","amount"],"additionalProperties":false}},"reason":{"type":"string","maxLength":300},"outcome":{"type":"string","enum":["refund","credit_balance"]}},"required":["invoiceId","outcome"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/checkout-sessions":{"post":{"summary":"Create a hosted checkout session","tags":["Hosted pages"],"security":[{"bearer":[]}],"x-scope":"sessions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"quantity":{"type":"integer","minimum":0,"maximum":1000000},"addon":{"type":"boolean"}},"required":["priceId"],"additionalProperties":false}},"customerId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"customer_email":{"type":"string","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_token":{"type":"string","maxLength":300},"success_url":{"type":"string","maxLength":2000,"format":"uri"},"cancel_url":{"type":"string","maxLength":2000,"format":"uri"},"coupon":{"type":"string","maxLength":40}},"required":["items","success_url","cancel_url"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/portal-sessions":{"post":{"summary":"Create a customer portal session (publishable keys must send a customer_token minted by your server)","tags":["Hosted pages"],"security":[{"bearer":[]}],"x-scope":"sessions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"customer_token":{"type":"string","maxLength":300},"return_url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["customerId","return_url"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/customers/{id}/token":{"post":{"summary":"Mint a short-lived customer token for the browser (secret keys only)","tags":["Hosted pages"],"security":[{"bearer":[]}],"x-scope":"sessions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a webhook endpoint (the signing secret is shown once)","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"maxItems":30,"type":"array","items":{"type":"string","maxLength":60}},"description":{"type":"string","maxLength":200}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test event","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"Recent deliveries","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/events":{"get":{"summary":"List events","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":true,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","maxLength":60}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}}}}