Skip to content

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 error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/public/card-update/string"
// JSON object. The OpenAPI document does not list its fields.

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 error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X POST "$GIEP_API_URL/public/card-update/string/complete"
// JSON object. The OpenAPI document does not list its fields.

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

  • clientTokenstring
    min 1 chars · max 4096 chars

Responses

  • 200Success
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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

  • storePublicIdstringrequired
    min 3 chars · max 64 chars
  • emailstring · emailrequired

Responses

  • 202Success
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 202 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/public/portal/session"
// JSON object. The OpenAPI document does not list its fields.

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"

  • typestringrequired
    Alwayscancel
  • reasonstringrequired
    One oftoo_expensivenot_usingswitchingother
  • reasonTextstring
    max 500 chars

type: "pause"

  • typestringrequired
    Alwayspause
  • monthsintegerrequired
    min 1 · max 3

type: "resume"

  • typestringrequired
    Alwaysresume

type: "update_card"

  • typestringrequired
    Alwaysupdate_card

Responses

  • 200Success
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Unique 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

  • declineCategorystring
    One ofsoftinsufficient_fundsauthentication_required
  • processorAccountIdstring · uuid
  • runIdstring · uuid
  • limitinteger
    min 1 · max 500

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 · uuidrequired
  • namestringrequired
    min 1 chars · max 80 chars
  • descriptionstring
    max 500 chars
  • intervalstringrequired
    One ofdayweekmonthyear
  • intervalCountinteger
    Default 1min 1 · max 365
  • pricesarray<object>required
    min 1 items · max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0
  • setupFeesarray<object>
    max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0
  • trialDaysinteger
    min 0 · max 365
  • verificationAmountsarray<object>
    max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 · uuid
  • namestringrequired
    min 1 chars · max 80 chars
  • descriptionstring
    max 500 chars
  • intervalstringrequired
    One ofdayweekmonthyear
  • intervalCountinteger
    Default 1min 1 · max 365
  • pricesarray<object>required
    min 1 items · max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0
  • setupFeesarray<object>
    max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0
  • trialDaysinteger
    min 0 · max 365
  • verificationAmountsarray<object>
    max 20 items
    Each item has 2 fields
    • currencystringrequired
      3 chars
    • amountintegerrequired
      greater than 0

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • dunningPolicyobjectnullable
    Fields: 4 fields
    • retryDaysobjectrequired
      Fields: 4 fields
      • softarray<integer>required
        max 8 items
      • insufficient_fundsarray<integer>required
        max 8 items
      • authentication_requiredarray<integer>required
        max 8 items
      • hardarray<integer>required
        max 8 items
    • finalActionstringrequired
      One ofunpaidcancelled
    • maxRetriesintegerrequired
      min 0 · max 8
    • windowDaysintegerrequired
      min 1 · max 60
  • runsPausedboolean
  • saveOfferPauseMonthsintegernullable
    min 1 · max 3

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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

  • statusstring
    One ofincompletetrialingactivepast_dueunpaidpausedcancelledexpired
  • storeIdstring · uuid
  • customerIdstring · uuid
  • limitinteger
    min 1 · max 500

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
curl -X GET "$GIEP_API_URL/v1/subscriptions" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

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-Keystringrequired

    Unique 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 · uuidrequired
  • paymentIdstring · uuidrequired
  • emailstring · email
  • customerIdstring · uuid

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • atPeriodEndboolean
    Default true
  • reasonstring
    One oftoo_expensivenot_usingswitchingother
  • reasonTextstring
    max 500 chars

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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-Keystringrequired

    Required 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 409 request_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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.

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 error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL
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.
Subscriptions · API reference · GIEP