> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # Start a plan subscription > Returns a Stripe Checkout URL that subscribes the workspace to Starter, Growth or Scale. One paid subscription per workspace: a new checkout expires the previous unpaid session, so only the newest one can be paid. USD only. The plan changes when Stripe reports the subscription active, not on the redirect. Not charged in credits and not capped, so a workspace at its Free limit can upgrade. Served by the Activity host for all products. Read-only and publishable keys get 403. ## OpenAPI ````yaml /api-reference/activity.json post /billing/checkout openapi: 3.0.3 info: title: Lumeus Activity API version: '2026-09-15' description: >- Lumeus Activity API on Stellar. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet is free: Testnet requests cost no credits and are never billed. Each organization can make 10,000 Testnet requests a day across Activity, Assets and RPC (unlimited on Enterprise); the count resets at 00:00 UTC, and a request over it answers 429 rate_limited with Retry-After set to the seconds until then. Mainnet requests draw from the plan's monthly credits. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer `. Testnet: `lum_test_…`; Mainnet: `lum_live_…`. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable `lum_pub_…` keys call the GET data routes only, from an allowed browser origin. Webhook keys (`whk_…`) are not accepted here. - **Headers.** Every response except `GET /readyz` carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON with a machine-readable code (see [errors](/guides/errors)). A path with an empty, `.` or `..` segment answers 400 invalid_request, a trailing slash answers 404 not_found, and a method the path does not accept answers 405 with an Allow header. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://api-testnet.lumeus.dev description: Testnet (default) - url: https://api.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: Queries description: >- Decoded Stellar history: the token movements and contract events of an account, asset, contract or transaction, the network feed, contract-event topic search and transaction headers. - name: Results description: >- Recover the saved result of a long prepaid request without running it again. Only prepaid accounts receive operation IDs; every other account gets 404 here. - name: Workspace description: >- Your workspace (organization): its name, plan, current period usage and API base URLs. Served by the Activity host for every product. - name: API keys description: >- Create, list, update, rotate and revoke the `lum_` keys used by the Activity API, the Assets API and RPC. - name: Usage description: >- Credits and requests used, the free Testnet daily count, per-route breakdowns, time series and the request log of your keys. - name: Billing description: >- The public plan catalog, plan subscriptions through Stripe Checkout, the billing portal and payment status. - name: Retired description: >- Routes kept only so old clients get a clear answer. Do not use them in new code. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /billing/checkout: post: tags: - Billing summary: Start a plan subscription description: >- Returns a Stripe Checkout URL that subscribes the workspace to Starter, Growth or Scale. One paid subscription per workspace: a new checkout expires the previous unpaid session, so only the newest one can be paid. USD only. The plan changes when Stripe reports the subscription active, not on the redirect. Not charged in credits and not capped, so a workspace at its Free limit can upgrade. Served by the Activity host for all products. Read-only and publishable keys get 403. operationId: startPlanSubscription requestBody: required: true content: application/json: schema: type: object properties: plan: type: string description: Self-serve plan to buy. enum: - starter - growth - scale required: - plan example: plan: growth responses: '200': description: A Stripe Checkout URL for the plan. content: application/json: schema: type: object properties: url: type: string description: Stripe Checkout URL. Open it in the browser. required: - url example: url: https://checkout.stripe.com/c/pay/cs_test_0000 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '400': $ref: '#/components/responses/HTTP400_14' '401': $ref: '#/components/responses/HTTP401' '403': $ref: '#/components/responses/HTTP403_3' '405': $ref: '#/components/responses/HTTP405_25' '409': $ref: '#/components/responses/HTTP409_6' '429': $ref: '#/components/responses/HTTP429_3' '502': $ref: '#/components/responses/HTTP502' '503': $ref: '#/components/responses/HTTP503_9' x-codeSamples: - lang: bash label: cURL source: >- curl --fail-with-body -sS -X POST 'https://api-testnet.lumeus.dev/billing/checkout' \ -H "Authorization: Bearer $LUMEUS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"plan":"growth"}' - lang: javascript label: JavaScript source: >- // Node 18+ (ES module) const res = await fetch('https://api-testnet.lumeus.dev/billing/checkout', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "plan": "growth" }), }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: |- import json import os import requests res = requests.post( "https://api-testnet.lumeus.dev/billing/checkout", headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"}, json={ "plan": "growth" }, timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: responses: HTTP400_14: description: >- Invalid input (code invalid_request). The message names the problem. Fix the request; do not retry it unchanged. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: plan must be starter, growth or scale request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP401: description: >- Missing, invalid, revoked or expired key, or a key for the other network (code unauthorized). Keys work only on the network they were created for. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized error: missing credentials request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP403_3: description: >- This key or account cannot call this route (code forbidden): for example a read-only key on a workspace route, or a publishable key on a route or from an origin it does not allow. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden error: >- this API key is read-only; use a full-access key or a signed-in session request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP405_25: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: 'method GET is not allowed on /billing/checkout; allowed: POST' request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP409_6: description: >- code conflict. reason subscription_exists: the workspace already has a subscription (change plans with `POST /billing/subscription` or in the portal). reason subscription_pending: a paid Checkout's subscription is still being applied. On a host where plan checkout is off, every call answers 409 with no reason. portal_url, when present, opens the billing portal. content: application/json: schema: type: object properties: error: type: string code: type: string reason: type: string enum: - subscription_exists - subscription_pending portal_url: type: string request_id: type: string required: - error - code example: code: conflict error: >- this workspace already has a subscription; change plans with POST /billing/subscription or manage it in the billing portal request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 reason: subscription_exists headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP429_3: description: >- The rate limit of this route was reached (code rate_limited). Wait Retry-After seconds. This route does not count toward the daily Testnet request cap, so its Retry-After is never the time until 00:00 UTC. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited error: rate limit exceeded request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer HTTP502: description: Stripe could not start the session (code internal_error). Retry later. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error error: could not start checkout request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP503_9: description: >- Temporarily unavailable (code unavailable). Wait Retry-After seconds and retry; do not assume the request failed permanently. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unavailable error: billing is not enabled request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ Retry-After: description: Seconds to wait before retrying. schema: type: integer schemas: Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer `. Testnet: `lum_test_…`; Mainnet: `lum_live_…`. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable `lum_pub_…` keys call the GET data routes only, from an allowed browser origin. Webhook keys (`whk_…`) are not accepted here. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.