Subscriptions
28 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.
Card-update page data (plan, price, card on file; no personal data)
GET/public/card-update/{token}
Resolves a card-update link (single use, 7 days). Unknown, expired and used links answer the same 404. Shows store, plan, price and the card on file; never personal data.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Path parameters
tokenstringrequired
Responses
- 200Success
- 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/public/card-update/string"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Server-side status fetch of the verification; switches the card once authorized
POST/public/card-update/{token}/complete
Reads the verification payment by a server-side status fetch. Once it is authorized the subscription takes the new token and its processor account, the authorisation is voided and a past-due invoice is retried at once.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Path parameters
tokenstringrequired
Responses
- 200Success
- 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/public/card-update/string/complete"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Start (or resume) the auth-only verification payment for the new card
POST/public/card-update/{token}/pay
Creates (or resumes, same key per link) an auth-only verification payment through the hosted fields; the outcome is read by complete, never from the browser.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Path parameters
tokenstringrequired
Request body · application/jsonrequired
clientTokenstringmin 1 chars · max 4096 chars
Responses
- 200Success
- 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/public/card-update/string/pay" \
-H "Content-Type: application/json" \
-d '{
"clientToken": "string"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Exchange a single-use link for a 12-hour portal session token
POST/public/portal/enter
Exchanges a single-use portal link (30 minutes) for a 12-hour portal session token, which the checkout keeps in an httpOnly cookie.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Request body · application/jsonrequired
tokenstringrequired
Responses
- 200Success
- 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/public/portal/enter" \
-H "Content-Type: application/json" \
-d '{
"token": "string"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Email a portal sign-in link (same answer for unknown emails)
POST/public/portal/request-link
Emails a portal link when the email has subscriptions in the store. The answer is the same for any email (no account enumeration). Rate limited.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
202
Request body · application/jsonrequired
storePublicIdstringrequiredmin 3 chars · max 64 charsemailstring · emailrequired
Responses
- 202Success
- 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 202 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/public/portal/request-link" \
-H "Content-Type: application/json" \
-d '{
"storePublicId": "string",
"email": "ana@example.com"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}The subscriber's subscriptions and invoices (header `x-portal-session`)
GET/public/portal/session
The subscriber's subscriptions in this store with invoices and the card on file. Authenticated by the x-portal-session header.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/public/portal/session"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Subscriber action: cancel at period end with a reason, pause 1-3 months, resume, update card
POST/public/portal/subscriptions/{id}/actions
Acts on the subscriber's own subscription only (404 otherwise): cancel at period end with a reason, pause 1-3 months, resume, or email a card-update link.
- Authentication
- None (public route)
- Permission
- Not stated
- Idempotency-Key
- Not used
- Success
200
Path parameters
idstringrequired
Request body · application/jsonrequired
type: "cancel"
typestringrequiredAlwayscancelreasonstringrequiredOne oftoo_expensivenot_usingswitchingotherreasonTextstringmax 500 chars
type: "pause"
typestringrequiredAlwayspausemonthsintegerrequiredmin 1 · max 3
type: "resume"
typestringrequiredAlwaysresume
type: "update_card"
typestringrequiredAlwaysupdate_card
Responses
- 200Success
- 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/public/portal/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/actions" \
-H "Content-Type: application/json" \
-d '{
"type": "cancel",
"reason": "too_expensive"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Recent billing runs with their reports
GET/v1/billing-runs
The merchant's recent daily billing runs: status, start/finish and the report (invoices created, charged, succeeded, failed, pending, skipped by reason, volume per currency, load per processor account).
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing-runs" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}What a run on `date` would charge (invoices, count, volume, per processor account, warnings)
GET/v1/billing-runs/preview
Invoices a run on date (YYYY-MM-DD = that day's 01:30 UTC run, or a timestamp; at is the older name; default tomorrow) would charge: the due invoices paged with offset / limit (max 200), count, volume per currency and per processor account, subscriptions without a payment method, each account's throughput estimate, and the accounts whose caps (counting what they already used today / this month) or throughput the run would exceed. Changes nothing.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing-runs/preview" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Retry a failed renewal cohort now
POST/v1/billing-runs/retry-failed
Renewals in dunning (failed, subscription past due), optionally of one decline category, processor account or run, up to limit (max 500). Each goes through the single "retry now" path (row lock, one attempt at a time, the dunning retry cap); the first wave of the per-account plan is charged now, the rest wait for the next run. Requires billing_run:manage. Audited. Idempotency-Key required: a replay answers the first result.
- Authentication
- API key (Bearer)
- Permission
billing_run:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredUnique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.
min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
declineCategorystringOne ofsoftinsufficient_fundsauthentication_requiredprocessorAccountIdstring · uuidrunIdstring · uuidlimitintegermin 1 · max 500
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/billing-runs/retry-failed" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-retry-failed-v1" \
-H "Content-Type: application/json" \
-d '{
"declineCategory": "soft",
"processorAccountId": "6a56728f-88e7-43cd-a890-8c9c7d0a",
"runId": "98a5da67-34fb-4c1f-a8ee-de661c13"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Run today's billing for this merchant now
POST/v1/billing-runs/run
The daily subscription-billing schedule does the same. Requires billing_run:manage. Audited.
- Authentication
- API key (Bearer)
- Permission
billing_run:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/billing-runs/run" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-run-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Charge a scheduled or failed invoice now
POST/v1/subscription-invoices/{id}/retry
Still one attempt at a time: refused while an earlier attempt is unresolved, and an uncollectible invoice (dunning over, or a hard decline) is refused. Requires billing_run:manage.
- Authentication
- API key (Bearer)
- Permission
billing_run:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscription-invoices/ceed276e-8b75-4d0a-a7a3-d04a8-73d/retry" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-retry-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}List subscription plans (every version)
GET/v1/subscription-plans
Plans of the merchant, optionally of one store (?storeId=). Archived versions are listed too.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscription-plans" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Create a plan
POST/v1/subscription-plans
Interval day 1-365, week 1-52, month 1-12 or year 1; one price per currency in integer minor units; optional setup fees and trial days. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
201
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
storeIdstring · uuidrequirednamestringrequiredmin 1 chars · max 80 charsdescriptionstringmax 500 charsintervalstringrequiredOne ofdayweekmonthyearintervalCountintegerDefault1min 1 · max 365pricesarray<object>requiredmin 1 items · max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
setupFeesarray<object>max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
trialDaysintegermin 0 · max 365verificationAmountsarray<object>max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
Responses
- 201Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 201 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscription-plans" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-subscription-plans-v1" \
-H "Content-Type: application/json" \
-d '{
"storeId": "4ca38853-83f8-4fc1-a3bc-a7234-702",
"name": "string",
"interval": "day",
"prices": [
{
"currency": "USD",
"amount": 4999
}
]
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}One plan version
GET/v1/subscription-plans/{id}
One plan version: interval, prices per currency (minor units), setup fees, trial days, status.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Path parameters
idstringrequired
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscription-plans/ceed276e-8b75-4d0a-a7a3-d04a8-73d" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Edit a plan (a new version once it has subscribers)
PUT/v1/subscription-plans/{id}
Without subscribers the plan is edited in place; with subscribers a new version is created (same plan key) and the old one is archived; existing subscribers keep their version. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
storeIdstring · uuidnamestringrequiredmin 1 chars · max 80 charsdescriptionstringmax 500 charsintervalstringrequiredOne ofdayweekmonthyearintervalCountintegerDefault1min 1 · max 365pricesarray<object>requiredmin 1 items · max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
setupFeesarray<object>max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
trialDaysintegermin 0 · max 365verificationAmountsarray<object>max 20 itemsEach item has 2 fields
currencystringrequired3 charsamountintegerrequiredgreater than 0
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X PUT "$GIEP_API_URL/v1/subscription-plans/ceed276e-8b75-4d0a-a7a3-d04a8-73d" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-subscription-plans-v1" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"interval": "day",
"prices": [
{
"currency": "USD",
"amount": 4999
}
]
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Archive a plan
DELETE/v1/subscription-plans/{id}
Archived plans are no longer sold but keep billing existing subscribers. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X DELETE "$GIEP_API_URL/v1/subscription-plans/ceed276e-8b75-4d0a-a7a3-d04a8-73d" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-subscription-plans-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Dunning policy and run settings
GET/v1/subscription-settings
The dunning policy in force (the default when the merchant set none), whether runs are paused, and the portal save offer.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscription-settings" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Set the dunning policy, pause or resume runs, portal save offer
PUT/v1/subscription-settings
Hard declines can never be retried. Requires billing_run:manage. Audited.
- Authentication
- API key (Bearer)
- Permission
billing_run:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
dunningPolicyobjectnullableFields: 4 fields
retryDaysobjectrequiredFields: 4 fields
softarray<integer>requiredmax 8 itemsinsufficient_fundsarray<integer>requiredmax 8 itemsauthentication_requiredarray<integer>requiredmax 8 itemshardarray<integer>requiredmax 8 items
finalActionstringrequiredOne ofunpaidcancelledmaxRetriesintegerrequiredmin 0 · max 8windowDaysintegerrequiredmin 1 · max 60
runsPausedbooleansaveOfferPauseMonthsintegernullablemin 1 · max 3
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X PUT "$GIEP_API_URL/v1/subscription-settings" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-subscription-settings-v1" \
-H "Content-Type: application/json" \
-d '{
"dunningPolicy": {
"retryDays": {
"soft": [
1
],
"insufficient_funds": [
1
],
"authentication_required": [
1
],
"hard": [
1
]
},
"finalAction": "unpaid",
"maxRetries": 1,
"windowDays": 1
},
"runsPaused": false,
"saveOfferPauseMonths": 1
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}List subscriptions
GET/v1/subscriptions
Subscriptions with plan name, subscriber email, status, amount, next bill date, card on file and MRR contribution. Filters: status, store, customer.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Query parameters
statusstringOne ofincompletetrialingactivepast_dueunpaidpausedcancelledexpiredstoreIdstring · uuidcustomerIdstring · uuidlimitintegermin 1 · max 500
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscriptions" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Start a subscription from a paid, tokenised payment
POST/v1/subscriptions
The payment must be succeeded, hold a reusable token (create it with saveForFutureUse) and be for the first period price, or the setup fee when the plan has a trial. A trial without a setup fee starts from an authorised auth-only verification (captureMethod: manual, the plan verification amount, default 1 minor unit), voided once the subscription holds the token. Renewals are charged only on the processor account that issued the token. Idempotent on the key. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
201
Headers
Idempotency-KeystringrequiredUnique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.
min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
planIdstring · uuidrequiredpaymentIdstring · uuidrequiredemailstring · emailcustomerIdstring · uuid
Responses
- 201Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 201 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-subscriptions-v1" \
-H "Content-Type: application/json" \
-d '{
"planId": "744bf63f-adad-4fdf-a476-09182-33d",
"paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}One subscription with invoices, attempts and authorization records
GET/v1/subscriptions/{id}
One subscription with its invoices and attempts (payment ids, decline categories) and every authorization record (terms version and hash, consent time, source).
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Path parameters
idstringrequired
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Cancel now or at period end
POST/v1/subscriptions/{id}/cancel
Cancelling now voids open invoices; nothing is refunded automatically. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
atPeriodEndbooleanDefaulttruereasonstringOne oftoo_expensivenot_usingswitchingotherreasonTextstringmax 500 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/cancel" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-cancel-v1" \
-H "Content-Type: application/json" \
-d '{
"atPeriodEnd": true,
"reason": "too_expensive",
"reasonText": "string"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Email the subscriber a single-use card-update link (7 days)
POST/v1/subscriptions/{id}/card-update-link
Emails the subscriber a single-use card-update link valid 7 days. Refused for cancelled or expired subscriptions. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/card-update-link" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-card-update-link-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Change plan: upgrade now with proration, downgrade at period end
POST/v1/subscriptions/{id}/change-plan
An upgrade creates a proration invoice (price difference for the whole days left, floored) charged by the next run or by retry; the plan switches when it is paid. A downgrade waits for the period end. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
planIdstring · uuidrequired
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/change-plan" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-change-plan-v1" \
-H "Content-Type: application/json" \
-d '{
"planId": "744bf63f-adad-4fdf-a476-09182-33d"
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Pause (until a date or indefinitely)
POST/v1/subscriptions/{id}/pause
No invoices while paused; a dated pause resumes itself at the next run. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
untilany
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/pause" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-pause-v1" \
-H "Content-Type: application/json" \
-d '{}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Resume a paused subscription (re-anchors the bill date to today)
POST/v1/subscriptions/{id}/resume
Resumes a paused subscription; the next period starts today and is billed by the next run. Open renewals of the old period are voided. Audited.
- Authentication
- API key (Bearer)
- Permission
subscription:manage- Idempotency-Key
- Required
- Success
200
Path parameters
idstringrequired
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/subscriptions/ceed276e-8b75-4d0a-a7a3-d04a8-73d/resume" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-resume-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}MRR command center summary per currency
GET/v1/subscriptions/mrr
MRR at the start and end of the window, new, expansion, contraction, churn (voluntary and involuntary), reactivation, net movement, ARR, subscriber counts, trial-to-paid, renewal and first-attempt success, recovery. Per currency, never converted; separate from processed volume.
- Authentication
- API key (Bearer)
- Permission
subscription:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/subscriptions/mrr" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}