Subscriptions

A plan is what a subscription costs and how often: a price in USD or EUR (price_amount, price_currency) or in an asset (amount, network, asset), an interval, and an optional free trial. The price and the interval never change; make a new plan for a new price.

await nowgate.plans.create({ … });

client.plans.create(…)

$nowgate->plans->create([…]);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Body

• namestringrequired

  1 to 100 characters.

• descriptionstring

  At most 500 characters.

• price_amountFiatAmount (string)

  An amount of a currency with at most two decimal places, e.g. "25.00".

• price_currencystring

  Example: "USD".

• amountAmount (string)

  A non-negative decimal amount in the asset's units, e.g. "12.5".

• networkNetwork (string)

  Network identifier; see GET /assets. New networks may be added.

• assetAssetSymbol (string)

  Asset symbol on the network; see GET /assets.

• intervalInterval (string)required

  One of: day, week, month, year.

• interval_countinteger

  Intervals per period (1 by default). A period is a day to a year.

  From 1 to 365.

• trial_daysinteger

  From 0 to 365.

• assetsarray of Pair (object)

  For a price in a currency, the pairs a subscriber may pay with; every pair by default.

  2 fields of Pair

  • networkNetwork (string)required

    Network identifier; see GET /assets. New networks may be added.

  • assetAssetSymbol (string)required

    Asset symbol on the network; see GET /assets.

• markup_bpsinteger

  From 0 to 1000.

• fee_paid_byFeePaidBy (string)

  Who bears Nowgate's fee. With payer, the payer sends enough for you to receive the whole price after the fee. The default is merchant.

  One of: merchant, payer.

• metadatamap of string

  At most 20 keys.

Responses

await nowgate.plans.retrieve(id);

client.plans.retrieve(id)

$nowgate->plans->retrieve($id);

Path parameters

• idPlanID (string)required

Responses

await nowgate.plans.list({ … });
for await (const item of nowgate.plans.listAll({ … })) { … }

client.plans.list(…)
for item in client.plans.list_all(…): …

$nowgate->plans->list([…]);
foreach ($nowgate->plans->listAll([…]) as $item) { … }

Query parameters

• limitinteger

  From 1 to 100. Default: 20.

• starting_afterPaymentID (string)

  Return the page after (older than) this ID.

• ending_beforePaymentID (string)

  Return the page before (newer than) this ID.

• statusPlanStatus (string)

  One of: active, archived.

Responses

Changes a plan's name, description, trial (for new subscriptions), assets, markup, fee mode, metadata or status. The assets, markup and fee mode apply to payments made after the change. An archived plan takes no new subscriptions; its subscriptions carry on.

await nowgate.plans.update(id, { … });

client.plans.update(id, …)

$nowgate->plans->update($id, […]);

Path parameters

• idPlanID (string)required

Body

• statusPlanStatus (string)

  One of: active, archived.

• namestring

  1 to 100 characters.

• descriptionstring

  At most 500 characters.

• trial_daysinteger

  From 0 to 365.

• assetsarray of Pair (object)
  2 fields of Pair

  • networkNetwork (string)required

    Network identifier; see GET /assets. New networks may be added.

  • assetAssetSymbol (string)required

    Asset symbol on the network; see GET /assets.

• markup_bpsinteger

  From 0 to 1000.

• fee_paid_byFeePaidBy (string)

  Who bears Nowgate's fee. With payer, the payer sends enough for you to receive the whole price after the fee. The default is merchant.

  One of: merchant, payer.

• metadatamap of string

  At most 20 keys.

Responses

Subscribes an email address to a plan. With a trial, the first invoice comes before the trial ends; without one, the first invoice is issued at once, and the subscription starts when it is paid: send the subscriber to latest_invoice.checkout_url. Nowgate emails the subscriber their invoices and reminders unless emails is false. At most 1,000 subscriptions a day per merchant by default (subscription_limit).

await nowgate.subscriptions.create({ … });

client.subscriptions.create(…)

$nowgate->subscriptions->create([…]);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Body

• planPlanID (string)required
• subscriberSubscriberInput (object)required
  3 fields of SubscriberInput

  • emailstringrequired

    At most 254 characters.

  • namestring

    At most 100 characters.

  • localestring

    The language of the emails and of the subscriber's page; English by default.

    One of: en, es, pt-BR, fr, de, it, tr, ru, zh-CN, ja.

• trial_daysinteger

  Overrides the plan's trial.

  From 0 to 365.

• emailsboolean

  Whether Nowgate emails the subscriber (true by default).

• external_idstring

  At most 100 characters.

• metadatamap of string

  At most 20 keys.

Responses

await nowgate.subscriptions.retrieve(id);

client.subscriptions.retrieve(id)

$nowgate->subscriptions->retrieve($id);

Path parameters

• idSubscriptionID (string)required

Responses

await nowgate.subscriptions.list({ … });
for await (const item of nowgate.subscriptions.listAll({ … })) { … }

client.subscriptions.list(…)
for item in client.subscriptions.list_all(…): …

$nowgate->subscriptions->list([…]);
foreach ($nowgate->subscriptions->listAll([…]) as $item) { … }

Query parameters

• limitinteger

  From 1 to 100. Default: 20.

• starting_afterPaymentID (string)

  Return the page after (older than) this ID.

• ending_beforePaymentID (string)

  Return the page before (newer than) this ID.

• statusSubscriptionStatus (string)

  One of: trialing, incomplete, active, past_due, unpaid, canceled.

• planPlanID (string)
• emailstring

  At most 254 characters.

• external_idstring

  At most 100 characters.

Responses

Moves the subscription to another plan from the next period (no proration), sets or undoes its cancellation at the end of the period, or changes the subscriber's details, the emails switch or the metadata.

await nowgate.subscriptions.update(id, { … });

client.subscriptions.update(id, …)

$nowgate->subscriptions->update($id, […]);

Path parameters

• idSubscriptionID (string)required

Body

• planPlanID (string)
• cancel_at_period_endboolean
• subscriberSubscriberInput (object)
  3 fields of SubscriberInput

  • emailstringrequired

    At most 254 characters.

  • namestring

    At most 100 characters.

  • localestring

    The language of the emails and of the subscriber's page; English by default.

    One of: en, es, pt-BR, fr, de, it, tr, ru, zh-CN, ja.

• emailsboolean
• metadatamap of string

  At most 20 keys.

Responses

Ends the subscription now and voids its open invoice. Nothing is refunded automatically: refund a payment with POST /payments/{id}/refunds. To end it at the end of the period instead, update it with cancel_at_period_end.

await nowgate.subscriptions.cancel(id);

client.subscriptions.cancel(id)

$nowgate->subscriptions->cancel($id);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

• idSubscriptionID (string)required

Responses

Gives the subscription a new subscriber_url; the old link stops working at once. For a subscriber whose link went astray.

await nowgate.subscriptions.rotateLink(id);

client.subscriptions.rotate_link(id)

$nowgate->subscriptions->rotateLink($id);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

• idSubscriptionID (string)required

Responses

await nowgate.invoices.retrieve(id);

client.invoices.retrieve(id)

$nowgate->invoices->retrieve($id);

Path parameters

• idInvoiceID (string)required

Responses

await nowgate.invoices.list({ … });
for await (const item of nowgate.invoices.listAll({ … })) { … }

client.invoices.list(…)
for item in client.invoices.list_all(…): …

$nowgate->invoices->list([…]);
foreach ($nowgate->invoices->listAll([…]) as $item) { … }

Query parameters

• limitinteger

  From 1 to 100. Default: 20.

• starting_afterPaymentID (string)

  Return the page after (older than) this ID.

• ending_beforePaymentID (string)

  Return the page before (newer than) this ID.

• subscriptionSubscriptionID (string)
• statusInvoiceStatus (string)

  One of: open, paid, void.

Responses

In the sandbox (and dev and test), moves the subscription's whole timeline earlier so that its next moment (to: next), or a named one, is now, then runs its schedule at once: a year of renewals, reminders and dunning in a few calls. In live this route doesn't exist: 404.

await nowgate.sandbox.simulateSubscription(id, { … });

client.sandbox.simulate_subscription(id, …)

$nowgate->sandbox->simulateSubscription($id, […]);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

• idSubscriptionID (string)required

Body

• action"advance"required
• tostring

  The moment to bring to now; next (the default) is the next one on its schedule.

  One of: next, invoice, due, grace_end, dunning_end, period_end.

Responses

In the sandbox (and dev and test), pays what remains of an open invoice: a payment as the invoice's page makes one, in the given asset (the plan's own for a price in an asset), then a simulated deposit of its amount. The payment finishes about 10 seconds later, and the invoice with it. In live this route doesn't exist: 404.

await nowgate.sandbox.simulateInvoice(id, { … });

client.sandbox.simulate_invoice(id, …)

$nowgate->sandbox->simulateInvoice($id, […]);

Headers

• Idempotency-Keystringrequired

  A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

  1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

• idInvoiceID (string)required

Body

• actionstringrequired

  pay: the only action.

  At most 20 characters.

• networkNetwork (string)

  Network identifier; see GET /assets. New networks may be added.

• assetAssetSymbol (string)

  Asset symbol on the network; see GET /assets.

Responses

Nowgate POSTs subscription.created, subscription.<status> on every change of a subscription's status (active, past_due, unpaid, canceled), subscription.renewed when a period begins paid for, and subscription.updated when its plan, cancellation, subscriber or emails switch changes. Signed and retried as payment events are.

Headers

• Nowgate-Signaturestringrequired
• Nowgate-Event-IdEventID (string)required

Body

• idEventID (string)required
• object"event"required
• typestringrequired

  subscription.created, subscription.<status>, subscription.renewed or subscription.updated.

• api_versionstringrequired

  Example: "2026-11-01".

• environmentstringrequired

  One of: live, sandbox, dev, test.

• created_atTimestamp (string (date-time))required
• dataobjectrequired
  1 fields

  • objectSubscription (object)required
    20 fields of Subscription

    • idSubscriptionID (string)required
    • object"subscription"required
    • statusSubscriptionStatus (string)required

      One of: trialing, incomplete, active, past_due, unpaid, canceled.

    • planPlanID (string)required
    • pending_planPlanID (string)

      A plan change, applied from the next period.

    • subscriberSubscriber (object)required
      3 fields of Subscriber

      • emailstring

        Cleared 30 days after the subscription ends.

      • namestring
      • localestringrequired
    • emailsbooleanrequired
    • trial_endTimestamp (string (date-time))
    • current_period_startTimestamp (string (date-time))
    • current_period_endTimestamp (string (date-time))
    • cancel_at_period_endbooleanrequired
    • canceled_atTimestamp (string (date-time))
    • cancel_reasonstring

      One of: merchant, subscriber, unpaid, incomplete.

    • latest_invoiceInvoiceSummary (object)
      6 fields of InvoiceSummary

      • idInvoiceID (string)required
      • statusInvoiceStatus (string)required

        One of: open, paid, void.

      • amount_dueAmount (string)required

        A non-negative decimal amount in the asset's units, e.g. "12.5".

      • amount_remainingAmount (string)required

        A non-negative decimal amount in the asset's units, e.g. "12.5".

      • due_atTimestamp (string (date-time))required
      • checkout_urlstring
    • subscriber_urlstring

      The subscriber's own page, to pay, cancel at the end of the period and see their invoices.

    • external_idstring
    • metadatamap of stringrequired
    • created_atTimestamp (string (date-time))required
    • updated_atTimestamp (string (date-time))required
    • versionintegerrequired

Responses

Nowgate POSTs invoice.created when a subscription's invoice is issued, invoice.paid once its payments are worth its amount, invoice.void when it won't be paid, and invoice.reopened in the rare case that a payment it counted is reversed. The invoice's payments send their own payment events.

Headers

• Nowgate-Signaturestringrequired
• Nowgate-Event-IdEventID (string)required

Body

• idEventID (string)required
• object"event"required
• typestringrequired

  invoice.created, invoice.paid, invoice.void or invoice.reopened.

• api_versionstringrequired

  Example: "2026-11-01".

• environmentstringrequired

  One of: live, sandbox, dev, test.

• created_atTimestamp (string (date-time))required
• dataobjectrequired
  1 fields

  • objectInvoice (object)required

    Amounts are in the currency (currency) or the asset (network, asset) of the plan's price.

    25 fields of Invoice

    • idInvoiceID (string)required
    • object"invoice"required
    • numberstringrequired

      Example: "INV-000123".

    • statusInvoiceStatus (string)required

      One of: open, paid, void.

    • subscriptionSubscriptionID (string)required
    • planPlanID (string)required
    • currencystring

      Example: "USD".

    • networkNetwork (string)

      Network identifier; see GET /assets. New networks may be added.

    • assetAssetSymbol (string)

      Asset symbol on the network; see GET /assets.

    • amount_dueAmount (string)required

      A non-negative decimal amount in the asset's units, e.g. "12.5".

    • amount_paidAmount (string)required

      What its payments are worth; a partial payment counts at its own quote.

    • amount_remainingAmount (string)required

      A non-negative decimal amount in the asset's units, e.g. "12.5".

    • overpaidbooleanrequired
    • period_startTimestamp (string (date-time))
    • period_endTimestamp (string (date-time))
    • issued_atTimestamp (string (date-time))required
    • due_atTimestamp (string (date-time))required
    • paid_atTimestamp (string (date-time))
    • voided_atTimestamp (string (date-time))
    • void_reasonstring

      One of: canceled, unpaid, replaced.

    • paymentsarray of PaymentID (string)required
    • checkout_urlstring

      The invoice's page, where the subscriber picks an asset and pays.

    • created_atTimestamp (string (date-time))required
    • updated_atTimestamp (string (date-time))required
    • versionintegerrequired

Responses

• idPlanID (string)required
• object"plan"required
• statusPlanStatus (string)required

  One of: active, archived.

• namestringrequired
• descriptionstring
• pricePrice (object)
  2 fields of Price

  • amountFiatAmount (string)required

    An amount of a currency with at most two decimal places, e.g. "25.00".

  • currencystringrequired

    Example: "USD".

• amountAmount (string)

  A non-negative decimal amount in the asset's units, e.g. "12.5".

• networkNetwork (string)

  Network identifier; see GET /assets. New networks may be added.

• assetAssetSymbol (string)

  Asset symbol on the network; see GET /assets.

• intervalInterval (string)required

  One of: day, week, month, year.

• interval_countintegerrequired
• trial_daysintegerrequired
• assetsarray of Pair (object)required
  2 fields of Pair

  • networkNetwork (string)required

    Network identifier; see GET /assets. New networks may be added.

  • assetAssetSymbol (string)required

    Asset symbol on the network; see GET /assets.

• markup_bpsintegerrequired
• fee_paid_byFeePaidBy (string)required

  Who bears Nowgate's fee. With payer, the payer sends enough for you to receive the whole price after the fee. The default is merchant.

  One of: merchant, payer.

• metadatamap of stringrequired
• created_atTimestamp (string (date-time))required
• updated_atTimestamp (string (date-time))required

• idSubscriptionID (string)required
• object"subscription"required
• statusSubscriptionStatus (string)required

  One of: trialing, incomplete, active, past_due, unpaid, canceled.

• planPlanID (string)required
• pending_planPlanID (string)

  A plan change, applied from the next period.

• subscriberSubscriber (object)required
  3 fields of Subscriber

  • emailstring

    Cleared 30 days after the subscription ends.

  • namestring
  • localestringrequired
• emailsbooleanrequired
• trial_endTimestamp (string (date-time))
• current_period_startTimestamp (string (date-time))
• current_period_endTimestamp (string (date-time))
• cancel_at_period_endbooleanrequired
• canceled_atTimestamp (string (date-time))
• cancel_reasonstring

  One of: merchant, subscriber, unpaid, incomplete.

• latest_invoiceInvoiceSummary (object)
  6 fields of InvoiceSummary

  • idInvoiceID (string)required
  • statusInvoiceStatus (string)required

    One of: open, paid, void.

  • amount_dueAmount (string)required

    A non-negative decimal amount in the asset's units, e.g. "12.5".

  • amount_remainingAmount (string)required

    A non-negative decimal amount in the asset's units, e.g. "12.5".

  • due_atTimestamp (string (date-time))required
  • checkout_urlstring
• subscriber_urlstring

  The subscriber's own page, to pay, cancel at the end of the period and see their invoices.

• external_idstring
• metadatamap of stringrequired
• created_atTimestamp (string (date-time))required
• updated_atTimestamp (string (date-time))required
• versionintegerrequired

Amounts are in the currency (currency) or the asset (network, asset) of the plan's price.

• idInvoiceID (string)required
• object"invoice"required
• numberstringrequired

  Example: "INV-000123".

• statusInvoiceStatus (string)required

  One of: open, paid, void.

• subscriptionSubscriptionID (string)required
• planPlanID (string)required
• currencystring

  Example: "USD".

• networkNetwork (string)

  Network identifier; see GET /assets. New networks may be added.

• assetAssetSymbol (string)

  Asset symbol on the network; see GET /assets.

• amount_dueAmount (string)required

  A non-negative decimal amount in the asset's units, e.g. "12.5".

• amount_paidAmount (string)required

  What its payments are worth; a partial payment counts at its own quote.

• amount_remainingAmount (string)required

  A non-negative decimal amount in the asset's units, e.g. "12.5".

• overpaidbooleanrequired
• period_startTimestamp (string (date-time))
• period_endTimestamp (string (date-time))
• issued_atTimestamp (string (date-time))required
• due_atTimestamp (string (date-time))required
• paid_atTimestamp (string (date-time))
• voided_atTimestamp (string (date-time))
• void_reasonstring

  One of: canceled, unpaid, replaced.

• paymentsarray of PaymentID (string)required
• checkout_urlstring

  The invoice's page, where the subscriber picks an asset and pays.

• created_atTimestamp (string (date-time))required
• updated_atTimestamp (string (date-time))required
• versionintegerrequired