{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/saasbilling.io" } ], "info": { "name": "SaasBilling API Documentation", "_postman_id": "d3a1c7e8-dc7f-498e-a37f-4052645857db", "description": "SaasBilling provides a single REST API to manage subscribers, subscriptions, plans, entitlements, metered usage and invoices on top of Stripe. The subscriber portal is hosted by SaasBilling and the actual payment method is collected by Stripe. Authenticate with a project API key and call the v1 endpoints below.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Subscribers", "description": "Manage subscribers in your project", "item": [ { "name": "List subscribers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers", "query": [ { "key": "type", "value": "organization", "description": "Filter by subscriber type (\"user\" or \"organization\").", "disabled": false }, { "key": "email", "value": "user@example.com", "description": "Filter by exact email address.", "disabled": false }, { "key": "limit", "value": "25", "description": "Page size, 1-100. Defaults to 100.", "disabled": false }, { "key": "starting_after", "value": "sbr_01HXYZ", "description": "Cursor: the `id` of the last subscriber on the previous page.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/subscribers?type=organization&email=user%40example.com&limit=25&starting_after=sbr_01HXYZ" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the most recent subscribers in your project, newest first, with\nStripe-style cursor pagination: pass the last item's `id` as\n`starting_after` to fetch the next page, until `has_more` is `false`.\nUse the `email` filter to look one up by address, or `type` to narrow\nthe list to users or organizations." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"has_more\":false,\"data\":[{\"object\":\"subscriber\",\"id\":\"sbr_01HXYZ\",\"external_id\":\"user_12345\",\"type\":\"user\",\"email\":\"user@example.com\",\"name\":\"John Doe\",\"metadata\":[],\"created_at\":\"2026-05-20T10:00:00+00:00\",\"updated_at\":\"2026-05-20T10:00:00+00:00\"}]}", "name": "List wrapper. `data[]` items follow the Subscriber resource shape; `has_more` signals another page behind the `starting_after` cursor." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscribers:read`." } ] }, { "name": "Retrieve a subscriber", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id", "variable": [ { "id": "external_id", "key": "external_id", "value": "architecto", "description": "The external ID of the subscriber." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the subscriber identified by your application's `external_id`.\nUseful to verify SaasBilling has the latest profile information or to fetch\nthe linked Stripe customer id." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscriber\",\"id\":\"sbr_eusckdwi9h5zzvd7xksq\",\"external_id\":\"usr_x1dbyd2jdu1k\",\"type\":\"user\",\"email\":\"price.amber@example.org\",\"name\":\"Miss Jazlyn Keebler III\",\"metadata\":{},\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscribers:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Create or update a subscriber", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_id\":\"user_12345\",\"type\":\"user\",\"email\":\"user@example.com\",\"name\":\"John Doe\",\"currency\":\"EUR\",\"locale\":\"fr\",\"metadata\":{\"plan\":\"premium\"}}" }, "description": "Idempotently upserts a subscriber by `external_id`. Call this right after\na customer signs up in your application \u2014 SaasBilling will create the\nsubscriber on Stripe if needed and mirror the identity locally. Pass an\n`Idempotency-Key` header to safely retry on network errors." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscriber\",\"id\":\"sbr_ic0ln24bcbmpbhdbaffl\",\"external_id\":\"usr_6ma3t5jmdncx\",\"type\":\"user\",\"email\":\"wleuschke@example.net\",\"name\":\"Mina Bauch\",\"metadata\":{},\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscribers:write`." } ] }, { "name": "Update a subscriber", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id", "variable": [ { "id": "external_id", "key": "external_id", "value": "architecto", "description": "The external ID of the subscriber." } ] }, "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"organization\",\"email\":\"newemail@example.com\",\"name\":\"Jane Doe\",\"currency\":\"EUR\",\"locale\":\"fr\",\"metadata\":{\"plan\":\"basic\"}}" }, "description": "Partially updates a subscriber. Only the fields you send are changed;\nexisting email, type, name and metadata are preserved. Stripe is\nreconciled automatically." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscriber\",\"id\":\"sbr_rwnwgjxhifrs3elkbons\",\"external_id\":\"usr_ht2pxe6uxvqo\",\"type\":\"user\",\"email\":\"ferne52@example.com\",\"name\":\"Mr. Carey Smitham\",\"metadata\":{},\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscribers:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Delete a subscriber", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id", "variable": [ { "id": "external_id", "key": "external_id", "value": "architecto", "description": "The external ID of the subscriber." } ] }, "method": "DELETE", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes a subscriber. Active subscriptions are cancelled at the\nperiod end by Stripe; the local row is kept for historic invoice access." }, "response": [ { "header": [], "code": 204, "body": null, "name": "Subscriber soft-deleted." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscribers:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] }, { "name": "Subscriptions", "description": "Subscription lifecycle and listing", "item": [ { "name": "List a subscriber's subscriptions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/subscriptions", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/subscriptions", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "External identifier of the subscriber." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns every subscription for the subscriber, active ones first. Use\nthis to display a billing history page or to find the subscription id\nto cancel, swap or resume." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"data\":[{\"object\":\"subscription\",\"id\":\"sub_01HXYZ\",\"project_id\":\"1\",\"subscriber_id\":\"1\",\"plan_id\":\"1\",\"status\":\"active\",\"current_period_start\":\"2026-05-01T00:00:00+00:00\",\"current_period_end\":\"2026-06-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"seats\":5,\"included_seats\":3,\"metadata\":[],\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-01T00:00:00+00:00\"}]}", "name": "List of the subscriber's subscriptions, active subscriptions first. `data[]` items follow the Subscription resource shape." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Retrieve a subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscriptions\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscriptions\/:id", "variable": [ { "id": "id", "key": "id", "value": "sub_01JXY...", "description": "Subscription public id (sub_*) or numeric id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the subscription identified by its public id (`sub_*`) or numeric\nid. Includes the resolved plan, prices and current billing period bounds." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscription\",\"id\":\"sub_8xkorpcbz0llchq98drq\",\"project_id\":\"84\",\"subscriber_id\":\"44\",\"plan_id\":\"29\",\"status\":\"active\",\"current_period_start\":\"2026-10-01T00:00:00+00:00\",\"current_period_end\":\"2026-11-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"complimentary\":false,\"complimentary_until\":null,\"metadata\":{},\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Give a plan for free", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/complimentary", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/complimentary", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "The external ID of the subscriber." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan\":\"pro\",\"ends_at\":\"2026-12-31\",\"reason\":\"Partner school\"}" }, "description": "Gives the subscriber a plan with no card and no charge; needs the `subscriptions:complimentary` scope, which `*` keys lack (see \"Giving plans for free\")." }, "response": [ { "header": [], "code": 201, "body": "{\"object\":\"subscription\",\"id\":\"sub_01HXYZ\",\"project_id\":\"1\",\"subscriber_id\":\"1\",\"plan_id\":\"2\",\"status\":\"active\",\"current_period_start\":\"2026-10-08T12:00:00+00:00\",\"current_period_end\":null,\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"complimentary\":true,\"complimentary_until\":\"2026-12-31T23:59:59+00:00\",\"items\":[],\"seats\":null,\"included_seats\":null,\"metadata\":[],\"created_at\":\"2026-10-08T12:00:00+00:00\",\"updated_at\":\"2026-10-08T12:00:00+00:00\"}", "name": "The complimentary subscription. `complimentary` is `true`; `complimentary_until` is the end date or `null`." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:complimentary\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:complimentary`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"subscriber_not_found\",\n \"message\": \"Subscriber not found for this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#subscriber_not_found\"\n }\n}", "name": "Domain error: `subscriber_not_found`." }, { "header": [], "code": 409, "body": "{\n \"error\": {\n \"type\": \"complimentary_stripe_subscription_active\",\n \"message\": \"This subscriber already pays for a plan. Cancel that paid plan first, then give a plan for free.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_stripe_subscription_active\"\n }\n}", "name": "Domain error: `complimentary_stripe_subscription_active`." }, { "header": [], "code": 409, "body": "{\n \"error\": {\n \"type\": \"complimentary_already_active\",\n \"message\": \"This subscriber already has a plan for free. Change or end it instead.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_already_active\"\n }\n}", "name": "Domain error: `complimentary_already_active`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_plan_unavailable\",\n \"message\": \"This plan cannot be given right now. Pick an active plan of this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_plan_unavailable\"\n }\n}", "name": "Domain error: `complimentary_plan_unavailable`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_until_in_past\",\n \"message\": \"The end date has already passed. Pick a later date or leave it empty.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_until_in_past\"\n }\n}", "name": "Domain error: `complimentary_until_in_past`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_reason_required\",\n \"message\": \"Write a short reason so your team knows why this plan is free.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_reason_required\"\n }\n}", "name": "Domain error: `complimentary_reason_required`." } ] }, { "name": "Change a free plan", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/complimentary", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/complimentary", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "The external ID of the subscriber." } ] }, "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan\":\"team\",\"ends_at\":\"2027-01-31\",\"reason\":\"Moved to the team tier\"}" }, "description": "Changes the plan, end date or reason of the free plan; send only what changes, and `ends_at: null` to remove the end date." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscription\",\"id\":\"sub_01HXYZ\",\"project_id\":\"1\",\"subscriber_id\":\"1\",\"plan_id\":\"2\",\"status\":\"active\",\"current_period_start\":\"2026-10-08T12:00:00+00:00\",\"current_period_end\":null,\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"complimentary\":true,\"complimentary_until\":\"2026-12-31T23:59:59+00:00\",\"items\":[],\"seats\":null,\"included_seats\":null,\"metadata\":[],\"created_at\":\"2026-10-08T12:00:00+00:00\",\"updated_at\":\"2026-10-08T12:00:00+00:00\"}", "name": "The updated complimentary subscription." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:complimentary\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:complimentary`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"subscriber_not_found\",\n \"message\": \"Subscriber not found for this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#subscriber_not_found\"\n }\n}", "name": "Domain error: `subscriber_not_found`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"complimentary_not_found\",\n \"message\": \"This subscriber has no free plan to change or end.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_not_found\"\n }\n}", "name": "Domain error: `complimentary_not_found`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_plan_unavailable\",\n \"message\": \"This plan cannot be given right now. Pick an active plan of this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_plan_unavailable\"\n }\n}", "name": "Domain error: `complimentary_plan_unavailable`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_until_in_past\",\n \"message\": \"The end date has already passed. Pick a later date or leave it empty.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_until_in_past\"\n }\n}", "name": "Domain error: `complimentary_until_in_past`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"complimentary_reason_required\",\n \"message\": \"Write a short reason so your team knows why this plan is free.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_reason_required\"\n }\n}", "name": "Domain error: `complimentary_reason_required`." } ] }, { "name": "End a free plan", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/complimentary", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/complimentary", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "The external ID of the subscriber." } ] }, "method": "DELETE", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"Partnership ended\"}" }, "description": "Ends the free plan now and puts the subscriber back on your project's default plan, as the panel's \"End free plan\" does." }, "response": [ { "header": [], "code": 204, "body": null, "name": "Free plan ended; the subscriber is back on the default plan." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:complimentary\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:complimentary`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"subscriber_not_found\",\n \"message\": \"Subscriber not found for this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#subscriber_not_found\"\n }\n}", "name": "Domain error: `subscriber_not_found`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"complimentary_not_found\",\n \"message\": \"This subscriber has no free plan to change or end.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#complimentary_not_found\"\n }\n}", "name": "Domain error: `complimentary_not_found`." } ] } ] }, { "name": "Plans", "description": "List and retrieve plans in your project", "item": [ { "name": "List plans", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/plans", "query": [ { "key": "currency", "value": "USD", "description": "Filter plans by currency code (e.g. USD, EUR).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/plans?currency=USD" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the active plans in your project, each with its active prices\nand the currency they are billed in. Use this to render a pricing page in\nyour own UI; subscribers pick and pay for a plan inside the SaasBilling\nbilling portal (`POST \/api\/v1\/portal-sessions`).\n\nPlans the operator marked hidden are not listed here. A hidden plan is\nstill returned by `GET \/api\/v1\/plans\/{key}` and still applies to the\nsubscribers assigned to it." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"data\":[{\"object\":\"plan\",\"id\":\"1\",\"key\":\"pro_monthly\",\"locale\":\"en\",\"name\":\"Pro Monthly\",\"description\":\"Professional plan billed monthly.\",\"status\":\"active\",\"is_default\":false,\"metadata\":{\"highlight\":\"true\"},\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-01T00:00:00+00:00\",\"features\":[{\"key\":\"projects\",\"name\":\"Projects\",\"type\":\"quota\",\"value\":10},{\"key\":\"sso\",\"name\":\"SSO\",\"type\":\"boolean\",\"value\":true},{\"key\":\"ai_tokens\",\"name\":\"AI tokens\",\"type\":\"quota\",\"value\":100000}],\"prices\":[]}]}", "name": "List of active plans, hidden plans left out. `data[]` items follow the Plan resource shape, each with its catalog `features[]` and active `prices[]`. Use `features[]` to render what a plan includes without creating a subscriber, and `is_default` to resolve the project's default\/free tier \u2014 never infer it from `key`." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: plans:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `plans:read`." } ] }, { "name": "Retrieve a plan by key", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/plans\/:key", "query": [], "raw": "{{baseUrl}}\/api\/v1\/plans\/:key", "variable": [ { "id": "key", "key": "key", "value": "basic-monthly", "description": "The key of the plan." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single plan and its active prices, identified by the\nhuman-readable plan key (e.g. `pro`, `basic-monthly`). Prefer this over\nnumeric ids when wiring up your pricing UI." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"plan\",\"id\":\"1\",\"key\":\"pro_monthly\",\"locale\":\"en\",\"name\":\"Pro Monthly\",\"description\":\"Professional plan billed monthly.\",\"status\":\"active\",\"is_default\":false,\"metadata\":{\"highlight\":\"true\"},\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-01T00:00:00+00:00\",\"features\":[{\"key\":\"projects\",\"name\":\"Projects\",\"type\":\"quota\",\"value\":10},{\"key\":\"sso\",\"name\":\"SSO\",\"type\":\"boolean\",\"value\":true}],\"prices\":[]}", "name": "A single plan with its catalog `features[]` and active `prices[]`." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: plans:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `plans:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] }, { "name": "Portal", "description": "Whitelabel billing portal sessions", "item": [ { "name": "Create a billing portal session", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/portal-sessions", "query": [], "raw": "{{baseUrl}}\/api\/v1\/portal-sessions" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"subscriber_external_id\":\"user_12345\",\"return_url\":\"https:\\\/\\\/app.example.com\\\/account\",\"locale\":\"fr\"}" }, "description": "Issues a single-use magic link to the project's whitelabel SaasBilling\nbilling portal so the subscriber can choose or change a plan, update their\npayment method, view invoices and cancel on their own. Redirect them to\nthe returned `url`; when they leave the portal they are sent back to\n`return_url`.\n\nTreat `url` as opaque: its host is your verified custom domain when one is\nconfigured, otherwise the SaasBilling shared host. Do not parse or rebuild it." }, "response": [ { "header": [], "code": 200, "body": "{\"url\":\"https:\\\/\\\/billing.example.com\\\/portal\\\/abcdef0123456789\",\"expires_at\":\"2026-01-15T10:15:00+00:00\"}", "name": "Portal session created. Redirect the subscriber to the returned URL." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: portal:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `portal:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"subscriber_not_found\",\n \"message\": \"Subscriber not found for this project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#subscriber_not_found\"\n }\n}", "name": "Domain error: `subscriber_not_found`." }, { "header": [], "code": 409, "body": "{\n \"error\": {\n \"type\": \"stripe_not_connected\",\n \"message\": \"Connect and verify your Stripe account before using checkout or billing portal.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#stripe_not_connected\"\n }\n}", "name": "Domain error: `stripe_not_connected`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscriber_wrong_project\",\n \"message\": \"Subscriber does not belong to the authenticated project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#subscriber_wrong_project\"\n }\n}", "name": "Domain error: `subscriber_wrong_project`." } ] } ] }, { "name": "Entitlements", "description": "Resolve subscriber feature entitlements", "item": [ { "name": "Resolve a subscriber's entitlements", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/entitlements", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/entitlements", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "External identifier of the subscriber." } ] }, "method": "GET", "header": [ { "key": "If-None-Match", "value": "\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\"" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the resolved feature flags and limits the subscriber currently\nhas access to, based on their active subscription's plan. Cache this on\nthe client for 60 seconds \u2014 SaasBilling returns a strong `ETag` so you can\nrevalidate with `If-None-Match` for a cheap `304 Not Modified`.\n\nAn entry states what the plan *grants*, never what is consumed: SaasBilling\ndoes not know how many devices or projects you have created. Count usage in\nyour own application and compare it against `value` (`-1` means unlimited).\n\n`seats` is different, and is the one number here that is billed rather than\ngranted: it is the count of users the subscription currently pays for, and it\nis the **real** user count, not a count above an included allowance. A plan\nsold as \"first 3 users included, then 5.00 each\" reports `seats: 5` for a\nfive-user organisation, and the first three are billed at zero by the price\nitself. Enforce it directly; never apply an offset of your own. There is no\nendpoint for changing it \u2014 the subscriber does that in the hosted billing\nportal, and you learn about it here and from `subscription.updated`.\n\n`plan.included_seats` is the other half of that number: how many users the\nseat price bills at zero before it starts charging, or `null` when it\ncharges from the first user. Together with `seats` it is what lets you show\n\"5 of 3 included\" without a second call to the catalog endpoint. It\ndescribes *billing*, not permission \u2014 the limit you enforce is the plan's\nown quota entry (commonly `member`) in `entries`.\n\n`subscription` is `null` for a subscriber with no live subscription, and\n`plan.is_default` marks the project's free tier \u2014 never infer the free\nplan from `plan.key`, which each project chooses for itself." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"entitlements\",\"data\":{\"subscriber_id\":42,\"project_id\":7,\"subscription_id\":311,\"plan\":{\"key\":\"pro\",\"name\":\"Pro\",\"description\":\"Professional plan.\",\"is_default\":false,\"interval_unit\":\"month\",\"interval_count\":1,\"included_seats\":3},\"seats\":5,\"subscription\":{\"status\":\"active\",\"cancel_at\":null,\"current_period_start\":\"2026-06-01T00:00:00+00:00\",\"current_period_end\":\"2026-07-01T00:00:00+00:00\",\"trial_ends_at\":null},\"entries\":[{\"key\":\"projects\",\"type\":\"quota\",\"value\":5,\"labels\":[],\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\",\"meter_key\":\"project_events\"},{\"key\":\"sso\",\"type\":\"boolean\",\"value\":true,\"labels\":[],\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\",\"meter_key\":null},{\"key\":\"support\",\"type\":\"text\",\"value\":\"knowledge_base\",\"labels\":{\"en\":\"Knowledge base\",\"tr\":\"Bilgi bankas\\u0131\"},\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\",\"meter_key\":null}],\"generated_at\":\"2026-06-10T12:00:00+00:00\"}}", "name": "Returned with `Cache-Control: private, max-age=60` and a strong `ETag` of the entitlement content (`generated_at` excluded, so a recomputed but unchanged set keeps its ETag). Send that ETag back as `If-None-Match` for a cheap revalidation." }, { "header": [], "code": 304, "body": null, "name": "Entitlement set unchanged since the ETag in `If-None-Match`." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: entitlements:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `entitlements:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] }, { "name": "Usage", "description": "Metered usage records and summaries", "item": [ { "name": "Get a subscriber's usage summary", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/usage", "query": [ { "key": "meter_key", "value": "api_calls", "description": "Meter key to summarise usage for.", "disabled": false }, { "key": "period", "value": "current", "description": "Period to aggregate: \"current\" (default \u2014 the active billing period), \"last\" (the billing period immediately before the current one), or \"last_30d\" (rolling window over the last 30 days).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/usage?meter_key=api_calls&period=current", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "External identifier of the subscriber." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Aggregates the subscriber's recorded usage for a single meter within the\ncurrent billing period. Returns `404 no_active_subscription` when the\nsubscriber has no active subscription to report against." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"usage_summary\",\"meter_key\":\"api_calls\",\"quantity\":1284,\"period_start\":\"2026-05-01T00:00:00+00:00\",\"period_end\":\"2026-06-01T00:00:00+00:00\",\"subscription_public_id\":\"sub_01JXY...\"}", "name": "Aggregated usage for the subscriber's active subscription, scoped to the current billing period." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: usage:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `usage:read`." }, { "header": [], "code": 404, "body": "{\"error\":{\"type\":\"no_active_subscription\",\"message\":\"Subscriber has no active subscription.\",\"doc_url\":\"\\\/docs#no_active_subscription\"}}", "name": "Subscriber has no active subscription to summarise usage against." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Record metered usage", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/usage", "query": [], "raw": "{{baseUrl}}\/api\/v1\/usage" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"subscriber_external_id\":\"user_12345\",\"meter_key\":\"api_calls\",\"quantity\":10,\"idempotency_key\":\"01JXY7QGJ8KZ...\",\"recorded_at\":\"2026-01-15T10:00:00Z\"}" }, "description": "Records a usage event against the subscriber's active metered\nsubscription item. Use this whenever the subscriber consumes a billable\nfeature (API call, transcoded video, sent email, \u2026).\n\n**This call is what creates the charge.** A metered line item does not\nexist until usage is recorded, so a call you skip is revenue the merchant\nnever bills, and a call you make twice is a customer overcharged \u2014 which is\nwhy `idempotency_key` is required rather than optional. Pass a stable key\nper logical event; the same key always returns the same record, so it is\nsafe to retry on network errors.\n\nThe recorded quantity is forwarded to Stripe and reflected in the next\ninvoice for the subscriber's current billing period. A metered amount is\ntherefore **not knowable in advance** \u2014 it can only be priced once the\nperiod closes. Do not build a UI that promises a total for the period in\nprogress; show consumption so far and say that usage is billed on top of\nthe recurring amount.\n\nA metered Meter and a `quota` feature are different things and often\nappear on the same plan: the quota is what the plan *grants* (read it from\nthe entitlements endpoint), the meter is what gets *billed* (this call)." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"usage_record\",\"id\":\"6\",\"meter_id\":\"8\",\"quantity\":81,\"recorded_at\":\"2026-10-22T07:20:11+00:00\",\"idempotency_key\":\"usage_znltcxz0otfyjnewju95jokn\",\"created_at\":\"2026-10-22T07:20:11+00:00\",\"updated_at\":\"2026-10-22T07:20:11+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: usage:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `usage:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"no_active_subscription\",\n \"message\": \"This subscriber has no active subscription.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#no_active_subscription\"\n }\n}", "name": "Domain error: `no_active_subscription`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_invalid_quantity\",\n \"message\": \"Usage quantity must be a positive integer.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_invalid_quantity\"\n }\n}", "name": "Domain error: `usage_invalid_quantity`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_correction_requires_sum_aggregation\",\n \"message\": \"Usage corrections require sum aggregation.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_correction_requires_sum_aggregation\"\n }\n}", "name": "Domain error: `usage_correction_requires_sum_aggregation`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_recorded_at_in_future\",\n \"message\": \"recorded_at must be at or before the current server time.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_recorded_at_in_future\"\n }\n}", "name": "Domain error: `usage_recorded_at_in_future`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_recorded_at_too_old\",\n \"message\": \"recorded_at is older than the accepted backdating window.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_recorded_at_too_old\"\n }\n}", "name": "Domain error: `usage_recorded_at_too_old`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_subscription_not_active\",\n \"message\": \"Subscription is not active; usage cannot be recorded.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_subscription_not_active\"\n }\n}", "name": "Domain error: `usage_subscription_not_active`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_no_metered_item_for_meter\",\n \"message\": \"No metered subscription item is bound to this meter.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#usage_no_metered_item_for_meter\"\n }\n}", "name": "Domain error: `usage_no_metered_item_for_meter`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"plan_cross_project_resource\",\n \"message\": \"Plan resource belongs to a different project.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#plan_cross_project_resource\"\n }\n}", "name": "Domain error: `plan_cross_project_resource`." } ] } ] }, { "name": "Invoices", "description": "List and retrieve invoices", "item": [ { "name": "List a subscriber's invoices", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscribers\/:external_id\/invoices", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscribers\/:external_id\/invoices", "variable": [ { "id": "external_id", "key": "external_id", "value": "user_12345", "description": "External identifier of the subscriber." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns invoices for the subscriber in reverse chronological order,\nincluding hosted invoice URLs and PDF links generated by Stripe. Ideal\nfor a \"Billing history\" tab in your application." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"data\":[{\"object\":\"invoice\",\"id\":\"inv_01HXYZ\",\"subscription_id\":\"1\",\"currency_id\":\"1\",\"currency_code\":\"USD\",\"status\":\"paid\",\"amount_due\":2900,\"amount_paid\":2900,\"hosted_invoice_url\":\"https:\\\/\\\/invoice.stripe.com\\\/i\\\/acct_xxx\\\/inv_xxx\",\"pdf_url\":\"https:\\\/\\\/pay.stripe.com\\\/invoice\\\/xxx\\\/pdf\",\"period_start\":\"2026-05-01T00:00:00+00:00\",\"period_end\":\"2026-06-01T00:00:00+00:00\",\"paid_at\":\"2026-05-02T10:00:00+00:00\",\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-02T10:00:00+00:00\"}]}", "name": "List of invoices for the subscriber, newest first. `data[]` items follow the Invoice resource shape." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: invoices:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `invoices:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Retrieve an invoice", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/invoices\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/invoices\/:id", "variable": [ { "id": "id", "key": "id", "value": "in_01JXY...", "description": "Invoice public id (in_*) or numeric id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single invoice by its public id (`in_*`) or numeric id,\nincluding the hosted Stripe URL and PDF download link." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"invoice\",\"id\":\"in_ocmaxxf8iaspsvjshvtf\",\"subscription_id\":\"34\",\"currency_id\":\"1\",\"status\":\"open\",\"amount_due\":49055,\"amount_paid\":0,\"hosted_invoice_url\":null,\"pdf_url\":null,\"period_start\":\"2026-10-01T00:00:00+00:00\",\"period_end\":\"2026-11-01T00:00:00+00:00\",\"paid_at\":null,\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: invoices:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `invoices:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] }, { "name": "Webhook Endpoints", "description": "Manage outbound webhook endpoints and discover subscribable events", "item": [ { "name": "List subscribable webhook event types", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-events", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-events" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Machine-readable catalog of every event type an endpoint can subscribe\nto. Use it to render a subscription picker or to validate your stored\nevent list against the current platform catalog instead of hardcoding\nevent names." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"data\":[{\"type\":\"subscriber.created\",\"label\":\"Subscriber created\"},{\"type\":\"subscription.created\",\"label\":\"Subscription created\"},{\"type\":\"entitlement.updated\",\"label\":\"Entitlements updated\"}]}", "name": "Every subscribable event type with its human-readable label." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:read`." } ] }, { "name": "List webhook endpoints", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns every webhook endpoint configured for your project, with their\ncurrent status and which event types they subscribe to. Use this to\nrender a webhooks settings page in your dashboard." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"data\":[{\"object\":\"webhook_endpoint\",\"id\":1,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/saasbilling\",\"description\":\"Production webhook\",\"status\":\"active\",\"event_types\":[\"subscription.created\",\"invoice.paid\"],\"consecutive_failures\":0,\"last_success_at\":\"2026-05-20T09:00:00+00:00\",\"last_failure_at\":null,\"signing_secret_grace_ends_at\":null,\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-20T09:00:00+00:00\"}]}", "name": "List of webhook endpoints. `data[]` items follow the WebhookEndpoint resource shape." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:read`." } ] }, { "name": "Retrieve a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints\/:id", "variable": [ { "id": "id", "key": "id", "value": 16, "description": "The webhook endpoint id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single webhook endpoint, including its current delivery\nstatus and last-success \/ failure counters." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"webhook_endpoint\",\"id\":13,\"url\":\"https:\\\/\\\/example.com\\\/webhooks\\\/bfc53181-d647-36b2-9080-f9c2b76006f4\",\"description\":\"Qui commodi incidunt iure odit.\",\"status\":\"active\",\"event_types\":[],\"consecutive_failures\":0,\"last_success_at\":null,\"last_failure_at\":null,\"signing_secret_grace_ends_at\":null,\"created_at\":\"2026-10-22T07:20:10+00:00\",\"updated_at\":\"2026-10-22T07:20:10+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:read\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:read`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Create a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/app.example.com\\\/webhooks\\\/saasbilling\",\"event_types\":[\"subscription.created\",\"invoice.paid\"],\"description\":\"Production receiver\"}" }, "description": "Registers a new HTTPS URL to receive SaasBilling webhook deliveries. The\nresponse contains a one-time-visible signing `secret` \u2014 store it\nsecurely on your server and use it to verify the `X-SaasBilling-Signature`\nheader on every delivery." }, "response": [ { "header": [], "code": 201, "body": "{\"object\":\"webhook_endpoint\",\"id\":1,\"url\":\"https:\\\/\\\/app.example.com\\\/webhooks\\\/saasbilling\",\"description\":\"Production receiver\",\"status\":\"active\",\"event_types\":[\"subscription.created\",\"invoice.paid\"],\"consecutive_failures\":0,\"last_success_at\":null,\"last_failure_at\":null,\"signing_secret\":\"whsec_01JXY7Z3K2M5N6P8Q9R0S1T2U3\",\"signing_secret_grace_ends_at\":null,\"created_at\":\"2026-05-20T10:00:00+00:00\",\"updated_at\":\"2026-05-20T10:00:00+00:00\"}", "name": "Webhook endpoint created. `signing_secret` is exposed **once** \u2014 store it securely; subsequent reads of this endpoint will omit it." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:write`." } ] }, { "name": "Update a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints\/:id", "variable": [ { "id": "id", "key": "id", "value": 16, "description": "The webhook endpoint id." } ] }, "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"http:\\\/\\\/www.bailey.biz\\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",\"event_types\":[\"architecto\"],\"description\":\"Eius et animi quos velit et.\",\"status\":\"architecto\"}" }, "description": "Updates the URL, description, subscribed events or active status of a\nwebhook endpoint. Setting `status=\"disabled\"` pauses deliveries without\nlosing the signing secret." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"webhook_endpoint\",\"id\":14,\"url\":\"https:\\\/\\\/example.com\\\/webhooks\\\/a4855dc5-0acb-33c3-b921-f4291f719ca0\",\"description\":null,\"status\":\"active\",\"event_types\":[],\"consecutive_failures\":0,\"last_success_at\":null,\"last_failure_at\":null,\"signing_secret_grace_ends_at\":null,\"created_at\":\"2026-10-22T07:20:11+00:00\",\"updated_at\":\"2026-10-22T07:20:11+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Delete a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints\/:id", "variable": [ { "id": "id", "key": "id", "value": 16, "description": "The webhook endpoint id." } ] }, "method": "DELETE", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Permanently removes a webhook endpoint. In-flight deliveries are\naborted; pending retries are discarded." }, "response": [ { "header": [], "code": 204, "body": null, "name": "Webhook endpoint deleted." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Rotate the signing secret", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-endpoints\/:id\/rotate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-endpoints\/:id\/rotate", "variable": [ { "id": "id", "key": "id", "value": 16, "description": "The webhook endpoint id." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Generates a new signing `secret` for the webhook endpoint and returns it\nin the response (one-time view). The previous secret continues to sign\ndeliveries for a 24-hour grace period so you can roll out the new one\nwithout dropping events." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"webhook_endpoint\",\"id\":1,\"url\":\"https:\\\/\\\/app.example.com\\\/webhooks\\\/saasbilling\",\"description\":\"Production receiver\",\"status\":\"active\",\"event_types\":[\"subscription.created\",\"invoice.paid\"],\"consecutive_failures\":0,\"last_success_at\":\"2026-05-20T09:00:00+00:00\",\"last_failure_at\":null,\"signing_secret\":\"whsec_NEW01JXY7Z3K2M5N6P8Q9R0S1T2\",\"signing_secret_grace_ends_at\":\"2026-05-21T10:00:00+00:00\",\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-20T10:00:00+00:00\"}", "name": "Rotated. The new `signing_secret` is returned **once** in plaintext. The previous secret remains valid for a grace window (see `signing_secret_grace_ends_at`)." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: webhooks:write\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `webhooks:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/saasbilling.io\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] }, { "name": "Health", "description": "Liveness probe for the public API", "item": [ { "name": "Liveness probe", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/health", "query": [], "raw": "{{baseUrl}}\/api\/v1\/health" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns `200 {\"status\":\"ok\"}` whenever the API process is up and serving\ntraffic. It requires no authentication and touches no datastore, so it\nlets you tell apart two failure modes that otherwise look identical: a\n`200` here next to a `5xx` on an authenticated call means the outage is\ndownstream (database \/ cache), not your API key; no response at all means\nthe service itself is unreachable.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"status\":\"ok\"}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }