Billing

Get available plans

GEThttps://api.paynow.gg/v1/stores/{storeId}/billing/plans

Retrieves the plans a store can subscribe to.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdstringRequired

Response

200OKPlanPreviewDto[]

Represents a publicly listed plan a store can subscribe to.

Show fields

idstringRequired

The unique identifier of the plan.

is_custombooleanRequired

Whether the plan is negotiated for a specific store rather than publicly offered.

namestringRequired

The display name of the plan.

platform_fee_rateintegerRequired

The platform fee charged on the store's revenue, in basis points.

subscription_price_monthlyintegerRequired

The monthly subscription price, in the smallest currency unit.

descriptionstringOptional

The description of the plan.

inherits_from_plan_idstringOptional

The identifier of the plan this one inherits its limits and feature flags from, if any.

subscription_price_annuallyintegerOptional

The annual subscription price, in the smallest currency unit, when the plan is billed annually.

Failed requests return a PayNowError body. See the error response guide.

curl -X GET "https://api.paynow.gg/v1/stores/{storeId}/billing/plans" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.getPublicPlans();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.get("https://api.paynow.gg/v1/stores/{storeId}/billing/plans", headers=headers)

Response200

[
  {
    "id": "string",
    "is_custom": true,
    "name": "string",
    "platform_fee_rate": 0,
    "subscription_price_monthly": 0,
    "description": "string",
    "inherits_from_plan_id": "string",
    "subscription_price_annually": 0
  }
]

Change subscription plan

POSThttps://api.paynow.gg/v1/stores/{storeId}/billing/plans/change

Moves the store onto a different plan. When the change needs paying for, the response carries a 'session_url' the store owner must complete.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to change the plan for.

Request body

plan_idstringRequired

The identifier of the plan to move the store onto.

renewal_periodenumRequired

Specifies how often a subscription renews.

Possible enum values

monthly
The subscription renews every month.
annually
The subscription renews every year.

Response

200OKCheckoutSessionDto

Represents the outcome of a subscription change that may require the store owner to pay.

Show fields

requires_paymentbooleanRequired

Whether the change needs a payment before it takes effect.

session_urlstringOptional

The URL the store owner is sent to in order to complete payment. Null when 'requires_payment' is false.

Failed requests return a PayNowError body. See the error response guide.

curl -X POST "https://api.paynow.gg/v1/stores/{storeId}/billing/plans/change" \
  -H "Authorization: APIKey TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "string",
  "renewal_period": "monthly"
}'

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.changeSubscriptionPlan({
  plan_id: "string",
  renewal_period: "monthly",
});

import requests

headers = {"Authorization": "APIKey TOKEN"}
payload = {
    "plan_id": "string",
    "renewal_period": "monthly",
}
response = requests.post("https://api.paynow.gg/v1/stores/{storeId}/billing/plans/change", headers=headers, json=payload)

Response200

{
  "requires_payment": true,
  "session_url": "string"
}

Continue current subscription

POSThttps://api.paynow.gg/v1/stores/{storeId}/billing/plans/continue

Cancels a pending downgrade or cancellation, keeping the store on its current plan.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to keep on its current plan.

Response

204No Content

Failed requests return a PayNowError body. See the error response guide.

curl -X POST "https://api.paynow.gg/v1/stores/{storeId}/billing/plans/continue" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

await paynow.billing.continueCurrentSubscription();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.post("https://api.paynow.gg/v1/stores/{storeId}/billing/plans/continue", headers=headers)

Change subscription payment method

POSThttps://api.paynow.gg/v1/stores/{storeId}/billing/payment-method/change

Starts a session for the store owner to replace the card the subscription is billed to.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to change the payment method for.

Response

200OKCheckoutSessionDto

Represents the outcome of a subscription change that may require the store owner to pay.

Show fields

requires_paymentbooleanRequired

Whether the change needs a payment before it takes effect.

session_urlstringOptional

The URL the store owner is sent to in order to complete payment. Null when 'requires_payment' is false.

Failed requests return a PayNowError body. See the error response guide.

curl -X POST "https://api.paynow.gg/v1/stores/{storeId}/billing/payment-method/change" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.changeSubscriptionPaymentMethod();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.post("https://api.paynow.gg/v1/stores/{storeId}/billing/payment-method/change", headers=headers)

Response200

{
  "requires_payment": true,
  "session_url": "string"
}

Get billing details

GEThttps://api.paynow.gg/v1/stores/{storeId}/billing/details

Retrieves the billing address and tax details the store is invoiced under.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to retrieve billing details for.

Response

200OKStoreBillingDetailsDto

Represents the billing address and tax details a store is invoiced under.

Show fields

citystringOptional

The city of the billing address.

countrystringOptional

The country of the billing address.

line_1stringOptional

The first line of the billing street address.

line_2stringOptional

The second line of the billing street address, if any (apartment, suite, etc.).

postal_codestringOptional

The postal code or zip code of the billing address.

statestringOptional

The state or province of the billing address.

tax_idstringOptional

The tax identifier the store is invoiced under, if any.

Failed requests return a PayNowError body. See the error response guide.

curl -X GET "https://api.paynow.gg/v1/stores/{storeId}/billing/details" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.getStoreBillingDetails();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.get("https://api.paynow.gg/v1/stores/{storeId}/billing/details", headers=headers)

Response200

{
  "city": "string",
  "country": "string",
  "line_1": "string",
  "line_2": "string",
  "postal_code": "string",
  "state": "string",
  "tax_id": "string"
}

Update billing details

PUThttps://api.paynow.gg/v1/stores/{storeId}/billing/details

Replaces the billing address and tax details the store is invoiced under.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to update billing details for.

Request body

citystringOptional

The city of the billing address.

countrystringOptional

The country of the billing address.

line_1stringOptional

The first line of the billing street address.

line_2stringOptional

The second line of the billing street address, if any (apartment, suite, etc.).

postal_codestringOptional

The postal code or zip code of the billing address.

statestringOptional

The state or province of the billing address.

tax_idstringOptional

The tax identifier the store is invoiced under, if any.

Response

204No Content

Failed requests return a PayNowError body. See the error response guide.

curl -X PUT "https://api.paynow.gg/v1/stores/{storeId}/billing/details" \
  -H "Authorization: APIKey TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "string",
  "country": "string",
  "line_1": "string",
  "line_2": "string",
  "postal_code": "string",
  "state": "string",
  "tax_id": "string"
}'

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

await paynow.billing.updateStoreBillingDetails({
  city: "string",
  country: "string",
  line_1: "string",
  line_2: "string",
  postal_code: "string",
  state: "string",
  tax_id: "string",
});

import requests

headers = {"Authorization": "APIKey TOKEN"}
payload = {
    "city": "string",
    "country": "string",
    "line_1": "string",
    "line_2": "string",
    "postal_code": "string",
    "state": "string",
    "tax_id": "string",
}
response = requests.put("https://api.paynow.gg/v1/stores/{storeId}/billing/details", headers=headers, json=payload)

Get subscription invoices

GEThttps://api.paynow.gg/v1/stores/{storeId}/billing/invoices

Retrieves the invoices raised against the store's own subscription.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to retrieve invoices for.

Query parameters

limitintegerOptional

The maximum number of items to return in a single request.

afterFlakeIdOptional

Returns items after the specified ID. Used for forward pagination through results.

beforeFlakeIdOptional

Returns items before the specified ID. Used for backward pagination through results.

ascbooleanOptional

Determines the sort order of returned items. When true, items are returned in ascending order. When false, items are returned in descending order.

Response

200OKStoreInvoiceDto[]

Represents an invoice raised against a store's own subscription.

Show fields

idFlakeIdRequired

created_atstringRequired

When the invoice was raised.

currencystringRequired

The currency the invoice was issued in.

descriptionstringRequired

The description of what was billed.

gatewaystringRequired

The payment gateway that issued the invoice.

gateway_invoice_idstringRequired

The identifier of the invoice within the payment gateway.

invoice_urlstringRequired

The hosted invoice URL recorded when the invoice was raised. May expire; request 'invoices/{invoice_id}/url' for a freshly issued link.

is_paidbooleanRequired

Whether the invoice has been paid.

plan_pricing_idFlakeIdRequired

subscription_idFlakeIdRequired

totalintegerRequired

The invoiced total, in the smallest currency unit.

updated_atstringOptional

When the invoice was last updated.

Failed requests return a PayNowError body. See the error response guide.

curl -X GET "https://api.paynow.gg/v1/stores/{storeId}/billing/invoices" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.getStoreInvoices();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.get("https://api.paynow.gg/v1/stores/{storeId}/billing/invoices", headers=headers)

Response200

[
  {
    "id": "411486491630370816",
    "created_at": "2024-01-01T00:00:00Z",
    "currency": "string",
    "description": "string",
    "gateway": "string",
    "gateway_invoice_id": "string",
    "invoice_url": "string",
    "is_paid": true,
    "plan_pricing_id": "411486491630370816",
    "subscription_id": "411486491630370816",
    "total": 0,
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

Get invoice URL

GEThttps://api.paynow.gg/v1/stores/{storeId}/billing/invoices/{invoiceId}/url

Issues a fresh link to the hosted invoice. Prefer this over the 'invoice_url' carried by the invoice list, which is recorded once and may have expired.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store the invoice belongs to.

invoiceIdFlakeIdRequired

The ID of the invoice to link to.

Response

200OKInvoiceUrlDto

Represents a freshly issued link to a hosted invoice.

Show fields

urlstringRequired

The hosted invoice URL.

Failed requests return a PayNowError body. See the error response guide.

curl -X GET "https://api.paynow.gg/v1/stores/{storeId}/billing/invoices/{invoiceId}/url" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.getStoreInvoiceUrl("411486491630370816");

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.get("https://api.paynow.gg/v1/stores/{storeId}/billing/invoices/{invoiceId}/url", headers=headers)

Response200

{
  "url": "string"
}

Get billing status

GEThttps://api.paynow.gg/v1/stores/{storeId}/billing/status

Retrieves the store's plan, limits, feature flags and subscription state.

Headers

AuthorizationAPI KeyRequired

Authentication token for this request, sent as Authorization: APIKey TOKEN.

Path parameters

storeIdFlakeIdRequired

The ID of the store to retrieve billing status for.

Response

200OKStoreBillingStatusDto

Show fields

alertsStoreAlertDto[]Required

idFlakeIdRequired

admin_visiblebooleanRequired

created_atstringRequired

metadataobjectRequired

statusenumRequired

Possible enum values

info
warning
action_required
resolved

store_idFlakeIdRequired

store_visiblebooleanRequired

typeenumRequired

Possible enum values

other
excessive_chargeback_rate
kyc_required
business_details_required
increased_fraud_rate
unsupported_product
product_compliance_check
integration_issue
storefront_compliance
support_inquiry
feature_eligibility
feature_enrolled

action_linkstringOptional

action_required_atstringOptional

custom_messagestringOptional

custom_titlestringOptional

entity_idFlakeIdOptional

expires_atstringOptional

resolved_atstringOptional

resolved_byFlakeIdOptional

updated_atstringOptional

feature_flagsstring[]Required

is_lockedbooleanRequired

no_billing_detailsbooleanRequired

planPlanDtoRequired

idstringRequired

is_custombooleanRequired

namestringRequired

descriptionstringOptional

plan_limitsobjectRequired

plan_pricingPlanPricingDtoRequired

idFlakeIdRequired

begins_atstringRequired

plan_idstringRequired

platform_fee_rateintegerRequired

subscription_price_monthlyintegerRequired

ends_atstringOptional

subscription_price_annuallyintegerOptional

revenue_usageintegerRequired

store_idFlakeIdRequired

lock_reasonstringOptional

payment_methodSubscriptionPaymentMethodDtoOptional

Represents the payment method a store's subscription is billed to.

idstringRequired

The identifier of the payment method within the payment gateway.

typestringRequired

The kind of payment method, such as a card.

card_brandstringOptional

The card network, when the payment method is a card.

card_exp_monthintegerOptional

The month the card expires, when the payment method is a card.

card_exp_yearintegerOptional

The year the card expires, when the payment method is a card.

card_last4stringOptional

The last four digits of the card, when the payment method is a card.

subscriptionStoreSubscriptionDtoOptional

idFlakeIdRequired

cancel_at_period_endbooleanRequired

created_atstringRequired

currencystringRequired

current_period_endstringRequired

current_period_startstringRequired

gatewaystringRequired

gateway_checkout_idstringRequired

gateway_payment_method_idstringRequired

gateway_subscription_idstringRequired

plan_idstringRequired

statusenumRequired

Possible enum values

incomplete
trialing
active
requires_action
canceled

store_idFlakeIdRequired

cancel_atstringOptional

downgrade_period_end_plan_idstringOptional

ended_atstringOptional

updated_atstringOptional

Failed requests return a PayNowError body. See the error response guide.

curl -X GET "https://api.paynow.gg/v1/stores/{storeId}/billing/status" \
  -H "Authorization: APIKey TOKEN"

import { createManagementClient } from "@paynow-gg/typescript-sdk";

const paynow = createManagementClient({
  apiKey: "API_KEY",
  storeId: "STORE_ID",
});

const result = await paynow.billing.getStoreBillingStatus();

import requests

headers = {"Authorization": "APIKey TOKEN"}
response = requests.get("https://api.paynow.gg/v1/stores/{storeId}/billing/status", headers=headers)

Response200

{
  "alerts": [
    {
      "id": "411486491630370816",
      "admin_visible": true,
      "created_at": "2024-01-01T00:00:00Z",
      "metadata": {},
      "status": "info",
      "store_id": "411486491630370816",
      "store_visible": true,
      "type": "other",
      "action_link": "string",
      "action_required_at": "2024-01-01T00:00:00Z",
      "custom_message": "string",
      "custom_title": "string",
      "entity_id": "411486491630370816",
      "expires_at": "2024-01-01T00:00:00Z",
      "resolved_at": "2024-01-01T00:00:00Z",
      "resolved_by": "411486491630370816",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "feature_flags": [
    "string"
  ],
  "is_locked": true,
  "no_billing_details": true,
  "plan": {
    "id": "string",
    "is_custom": true,
    "name": "string",
    "description": "string"
  },
  "plan_limits": {},
  "plan_pricing": {
    "id": "411486491630370816",
    "begins_at": "2024-01-01T00:00:00Z",
    "plan_id": "string",
    "platform_fee_rate": 0,
    "subscription_price_monthly": 0,
    "ends_at": "2024-01-01T00:00:00Z",
    "subscription_price_annually": 0
  },
  "revenue_usage": 0,
  "store_id": "411486491630370816",
  "lock_reason": "string",
  "payment_method": {
    "id": "string",
    "type": "string",
    "card_brand": "string",
    "card_exp_month": 0,
    "card_exp_year": 0,
    "card_last4": "string"
  },
  "subscription": {
    "id": "411486491630370816",
    "cancel_at_period_end": true,
    "created_at": "2024-01-01T00:00:00Z",
    "currency": "string",
    "current_period_end": "2024-01-01T00:00:00Z",
    "current_period_start": "2024-01-01T00:00:00Z",
    "gateway": "string",
    "gateway_checkout_id": "string",
    "gateway_payment_method_id": "string",
    "gateway_subscription_id": "string",
    "plan_id": "string",
    "status": "incomplete",
    "store_id": "411486491630370816",
    "cancel_at": "2024-01-01T00:00:00Z",
    "downgrade_period_end_plan_id": "string",
    "ended_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}