{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/proxyon.teknoza.be" } ], "info": { "name": "ProxyOn API Documentation", "_postman_id": "4454a0ae-3c32-4bac-9b1f-c47971bcdd12", "description": "ProxyOn 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 ProxyOn 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%40example.com", "description": "Filter by exact email address.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/subscribers?type=organization&email=user%40example.com" }, "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 (up to 100). Use the\n`email` filter to look one up by address, or `type` to narrow the list to\nusers or organizations. Cursor pagination is not exposed yet \u2014 pivot\nbootstrap migrations should rely on these filters." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"list\",\"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." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscribers:read\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/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 Proxyon has the latest profile information or to fetch\nthe linked Stripe customer id." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscriber\",\"id\":\"sbr_cidicwud531rtdomve7u\",\"external_id\":\"usr_cixbojokeli6\",\"type\":\"user\",\"email\":\"price.amber@example.org\",\"name\":\"Miss Jazlyn Keebler III\",\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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\",\"metadata\":{\"plan\":\"premium\"}}" }, "description": "Idempotently upserts a subscriber by `external_id`. Call this right after\na customer signs up in your application \u2014 Proxyon 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_vj45sybaji6zmnhaeugu\",\"external_id\":\"usr_yqoelvt3yv0r\",\"type\":\"user\",\"email\":\"okon.justina@example.com\",\"name\":\"Misael Runte\",\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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\",\"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_xufe7szcgyq78ebjuql2\",\"external_id\":\"usr_xiwkagq7cvll\",\"type\":\"user\",\"email\":\"lafayette.considine@example.com\",\"name\":\"Mr. Adriel Romaguera\",\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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,\"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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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_k8hhj4w6x1i0zqbbtjcz\",\"project_id\":\"29\",\"subscriber_id\":\"11\",\"plan_id\":\"12\",\"status\":\"active\",\"current_period_start\":\"2026-06-01T00:00:00+00:00\",\"current_period_end\":\"2026-07-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] }, { "name": "Cancel a subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscriptions\/:id\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscriptions\/:id\/cancel", "variable": [ { "id": "id", "key": "id", "value": "sub_01JXY...", "description": "Subscription public id (sub_*) or numeric id." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"at_period_end\":true,\"reason\":\"Customer requested downgrade\"}" }, "description": "Cancels a subscription. By default it stays active until the end of the\ncurrent billing period; pass `at_period_end=false` to cancel immediately\nand prorate the unused time." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscription\",\"id\":\"sub_kdp9smztvtetz6ztemnl\",\"project_id\":\"39\",\"subscriber_id\":\"15\",\"plan_id\":\"15\",\"status\":\"active\",\"current_period_start\":\"2026-06-01T00:00:00+00:00\",\"current_period_end\":\"2026-07-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:write\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_already_canceled\",\n \"message\": \"Subscription is already canceled.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_already_canceled\"\n }\n}", "name": "Domain error: `subscription_already_canceled`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_not_actionable_cancel\",\n \"message\": \"Subscription state does not allow cancellation.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_not_actionable_cancel\"\n }\n}", "name": "Domain error: `subscription_not_actionable_cancel`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_missing_stripe_id\",\n \"message\": \"Subscription is missing its Stripe identifier.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_missing_stripe_id\"\n }\n}", "name": "Domain error: `subscription_missing_stripe_id`." } ] }, { "name": "Swap a subscription's plan price", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscriptions\/:id\/swap", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscriptions\/:id\/swap", "variable": [ { "id": "id", "key": "id", "value": "sub_01JXY...", "description": "Subscription public id (sub_*) or numeric id." } ] }, "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_price_id\":42,\"proration\":\"always\"}" }, "description": "Switches the subscription to a different `plan_price_id`. Stripe handles\nproration automatically \u2014 pass `proration=\"none\"` to skip it and bill\nthe new price starting from the next cycle." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscription\",\"id\":\"sub_vmiqlb0ahciyttxovcw2\",\"project_id\":\"42\",\"subscriber_id\":\"16\",\"plan_id\":\"16\",\"status\":\"active\",\"current_period_start\":\"2026-06-01T00:00:00+00:00\",\"current_period_end\":\"2026-07-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"metadata\":null,\"created_at\":\"2026-06-19T09:49:24+00:00\",\"updated_at\":\"2026-06-19T09:49:24+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:write\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_not_actionable_swap\",\n \"message\": \"Subscription state does not allow swapping.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_not_actionable_swap\"\n }\n}", "name": "Domain error: `subscription_not_actionable_swap`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_missing_stripe_id\",\n \"message\": \"Subscription is missing its Stripe identifier.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_missing_stripe_id\"\n }\n}", "name": "Domain error: `subscription_missing_stripe_id`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"plan_archived\",\n \"message\": \"Plan is archived and cannot be used for new subscriptions.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#plan_archived\"\n }\n}", "name": "Domain error: `plan_archived`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"plan_price_inactive\",\n \"message\": \"Plan price is inactive.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#plan_price_inactive\"\n }\n}", "name": "Domain error: `plan_price_inactive`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_price_not_synced\",\n \"message\": \"Subscription price is not synced to Stripe.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_price_not_synced\"\n }\n}", "name": "Domain error: `subscription_price_not_synced`." } ] }, { "name": "Resume a cancelled subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/subscriptions\/:id\/resume", "query": [], "raw": "{{baseUrl}}\/api\/v1\/subscriptions\/:id\/resume", "variable": [ { "id": "id", "key": "id", "value": "sub_01JXY...", "description": "Subscription public id (sub_*) or numeric id." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "idem_01JXY..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Reverts a subscription that was previously cancelled at period end. Only\nworks while the current billing period has not yet ended; after that the\nsubscription must be re-created." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"subscription\",\"id\":\"sub_cogmkt8wqnvmmvak7hyi\",\"project_id\":\"45\",\"subscriber_id\":\"17\",\"plan_id\":\"17\",\"status\":\"active\",\"current_period_start\":\"2026-06-01T00:00:00+00:00\",\"current_period_end\":\"2026-07-01T00:00:00+00:00\",\"trial_ends_at\":null,\"cancel_at\":null,\"canceled_at\":null,\"metadata\":null,\"created_at\":\"2026-06-19T09:49:24+00:00\",\"updated_at\":\"2026-06-19T09:49:24+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: subscriptions:write\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#insufficient_scope\"\n }\n}", "name": "Forbidden \u2014 API key lacks the required scope `subscriptions:write`." }, { "header": [], "code": 404, "body": "{\n \"error\": {\n \"type\": \"not_found\",\n \"message\": \"The requested resource was not found.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_already_canceled\",\n \"message\": \"Subscription is already canceled.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_already_canceled\"\n }\n}", "name": "Domain error: `subscription_already_canceled`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_cannot_resume\",\n \"message\": \"Subscription cannot be resumed in its current state.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_cannot_resume\"\n }\n}", "name": "Domain error: `subscription_cannot_resume`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_missing_stripe_id\",\n \"message\": \"Subscription is missing its Stripe identifier.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_missing_stripe_id\"\n }\n}", "name": "Domain error: `subscription_missing_stripe_id`." } ] } ] }, { "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 ProxyOn\nbilling portal (`POST \/api\/v1\/portal-sessions`)." }, "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\",\"interval_unit\":\"month\",\"interval_count\":1,\"trial_days\":14,\"metadata\":[],\"created_at\":\"2026-05-01T00:00:00+00:00\",\"updated_at\":\"2026-05-01T00:00:00+00:00\",\"prices\":[]}]}", "name": "List of active plans. `data[]` items follow the Plan resource shape (with `prices[]`)." }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: plans:read\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/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\":\"13\",\"key\":\"aut_adipisci\",\"locale\":\"en\",\"name\":\"Quidem nostrum Plan\",\"description\":\"\",\"status\":\"draft\",\"metadata\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+00:00\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"error\": {\n \"type\": \"insufficient_scope\",\n \"message\": \"API key lacks required scope: plans:read\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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\"}" }, "description": "Issues a single-use magic link to the project's whitelabel ProxyOn\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`." }, "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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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 Proxyon returns a strong `ETag` so you can\nrevalidate with `If-None-Match` for a cheap `304 Not Modified`." }, "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.\",\"interval_unit\":\"month\",\"interval_count\":1},\"seats\":5,\"entries\":[{\"key\":\"projects\",\"type\":\"quota\",\"value\":5,\"remaining\":3,\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\"},{\"key\":\"sso\",\"type\":\"boolean\",\"value\":true,\"remaining\":null,\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\"}],\"generated_at\":\"2026-06-10T12:00:00+00:00\"}}", "name": "Returned with `Cache-Control: private, max-age=60` and a strong `ETag` of the JSON body. 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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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": "feature_key", "value": "api_calls", "description": "Feature 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?feature_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": { "mode": "raw", "raw": "{\"feature_key\":\"b\",\"period\":\"current\"}" }, "description": "Aggregates the subscriber's recorded usage for a single metered feature\nwithin the current billing period. Returns `404 no_active_subscription`\nwhen the subscriber has no active subscription to report against." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"usage_summary\",\"feature_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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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\",\"feature_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\nPass a stable `idempotency_key` per logical event \u2014 the same key always\nreturns the same record, so it is safe to retry on network errors. The\nrecorded quantity is forwarded to Stripe and reflected in the next\ninvoice for the subscriber's current billing period." }, "response": [ { "header": [], "code": 200, "body": "{\"object\":\"usage_record\",\"id\":\"2\",\"feature_id\":\"7\",\"quantity\":7,\"recorded_at\":\"2026-06-19T09:49:24+00:00\",\"idempotency_key\":\"usage_c1chv8pgu595azfpwdxsd6qa\",\"created_at\":\"2026-06-19T09:49:24+00:00\",\"updated_at\":\"2026-06-19T09:49:24+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/docs#usage_subscription_not_active\"\n }\n}", "name": "Domain error: `usage_subscription_not_active`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_unsupported_feature_type\",\n \"message\": \"Feature type does not support usage records.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#usage_unsupported_feature_type\"\n }\n}", "name": "Domain error: `usage_unsupported_feature_type`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"usage_feature_not_in_plan\",\n \"message\": \"Feature is not part of the subscription plan.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#usage_feature_not_in_plan\"\n }\n}", "name": "Domain error: `usage_feature_not_in_plan`." }, { "header": [], "code": 422, "body": "{\n \"error\": {\n \"type\": \"subscription_no_items\",\n \"message\": \"Subscription has no priced items.\",\n \"doc_url\": \"https:\/\/proxyon.teknoza.be\/docs#subscription_no_items\"\n }\n}", "name": "Domain error: `subscription_no_items`." }, { "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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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_kzgiimwbgpfca6t8tif0\",\"subscription_id\":\"8\",\"currency_id\":\"1\",\"status\":\"open\",\"amount_due\":49055,\"amount_paid\":0,\"hosted_invoice_url\":null,\"pdf_url\":null,\"period_start\":\"2026-06-01T00:00:00+00:00\",\"period_end\":\"2026-07-01T00:00:00+00:00\",\"paid_at\":null,\"created_at\":\"2026-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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 for your project", "item": [ { "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\\\/proxyon\",\"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:\/\/proxyon.teknoza.be\/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\":3,\"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-06-19T09:49:23+00:00\",\"updated_at\":\"2026-06-19T09:49:23+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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\\\/proxyon\",\"event_types\":[\"subscription.created\",\"invoice.paid\"],\"description\":\"Production receiver\"}" }, "description": "Registers a new HTTPS URL to receive Proxyon webhook deliveries. The\nresponse contains a one-time-visible signing `secret` \u2014 store it\nsecurely on your server and use it to verify the `Proxyon-Signature`\nheader on every delivery." }, "response": [ { "header": [], "code": 201, "body": "{\"object\":\"webhook_endpoint\",\"id\":1,\"url\":\"https:\\\/\\\/app.example.com\\\/webhooks\\\/proxyon\",\"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:\/\/proxyon.teknoza.be\/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\":4,\"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-06-19T09:49:24+00:00\",\"updated_at\":\"2026-06-19T09:49:24+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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/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\\\/proxyon\",\"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:\/\/proxyon.teknoza.be\/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:\/\/proxyon.teknoza.be\/docs#not_found\"\n }\n}", "name": "Not Found \u2014 the referenced resource does not exist for this project." } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }