Tier Groups

Get customer tier groups

GEThttps://api.paynow.gg/v1/store/tier-groups

Retrieves tier group state for a logged in customer. Returns an empty array if not logged in.

Headers

AuthorizationCustomer tokenRequired

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

Response

200OKCustomerTierGroupDto[]

Show fields

active_product_idFlakeIdRequired

currencystringRequired

The settlement currency code (e.g., "usd").

next_billing_amountintegerRequired

The next billing amount in the smallest currency unit (e.g., cents) in the settlement currency.

next_billing_presentment_amountintegerRequired

The next billing amount in the smallest currency unit (e.g., cents) in the customer-facing presentment currency.

next_renewal_atstringRequired

The date and time of the next subscription renewal for this tier group.

presentment_currencystringRequired

The customer-facing presentment currency code (e.g., "eur").

tier_group_idFlakeIdRequired

pending_change_product_idFlakeIdOptional

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

curl -X GET "https://api.paynow.gg/v1/store/tier-groups" \
  -H "Authorization: Customer TOKEN"

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

const paynow = createStorefrontClient({
  storeId: "STORE_ID",
  customerToken: "CUSTOMER_TOKEN",
});

const result = await paynow.tierGroups.getCustomerTierGroups();

import requests

headers = {"Authorization": "Customer TOKEN"}
response = requests.get("https://api.paynow.gg/v1/store/tier-groups", headers=headers)

Response200

[
  {
    "active_product_id": "411486491630370816",
    "currency": "string",
    "next_billing_amount": 0,
    "next_billing_presentment_amount": 0,
    "next_renewal_at": "2024-01-01T00:00:00Z",
    "presentment_currency": "string",
    "tier_group_id": "411486491630370816",
    "pending_change_product_id": "411486491630370816"
  }
]

Update subscription tier group

POSThttps://api.paynow.gg/v1/store/tier-groups/{id}/change

Upgrades or downgrades an existing subscription tier group. The customer must have an active subscription within this tier group.

Headers

AuthorizationCustomer tokenRequired

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

Path parameters

idFlakeIdRequired

Request body

target_product_idFlakeIdRequired

verification_codestringOptional

A verification code sent to the customer's subscription billing e-mail. Pass this if the `status` field on the `subscription_change` object equals `pending_verification`.

Response

200OKUpdateSubscriptionResponseDto

Response returned after a subscription change is initiated.

Show fields

subscription_changeSubscriptionChangeDtoRequired

A pending or applied change to a subscription.

created_atstringRequired

idFlakeIdRequired

linesSubscriptionChangeLineDto[]Required

A single line item within a subscription change.

amountSubscriptionChangeLineAmountDtoRequired

→ SubscriptionChangeLineAmountDto

idFlakeIdRequired

is_deletedbooleanRequired

Whether this line is being removed by the change.

presentment_amountSubscriptionChangeLineAmountDtoRequired

→ SubscriptionChangeLineAmountDto

priceintegerRequired

Base price in smallest settlement currency units.

productSubscriptionChangeLineProductDtoRequired

→ SubscriptionChangeLineProductDto

prorated_amountintegerRequired

Prorated charge for this line in smallest settlement currency units.

prorated_presentment_amountintegerRequired

Prorated charge for this line in smallest presentment currency units.

remaining_minutesintegerRequired

Minutes remaining in the billing period at the time of change - used to calculate proration.

tax_inclusivebooleanRequired

Whether tax is included in the base price.

total_minutesintegerRequired

Total minutes in the billing period - used to calculate proration.

subscription_line_idFlakeIdOptional

next_billing_amountSubscriptionChangeAmountDtoRequired

Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents).

currencystringRequired

ISO 4217 currency code, in lowercase.

discountintegerRequired

Total discount applied, in smallest currency units.

subtotalintegerRequired

Base amount before discounts or tax, in smallest currency units.

taxintegerRequired

Tax amount, in smallest currency units.

totalintegerRequired

Amount due after discounts and tax, in smallest currency units.

next_billing_presentment_amountSubscriptionChangeAmountDtoRequired

Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents).

currencystringRequired

ISO 4217 currency code, in lowercase.

discountintegerRequired

Total discount applied, in smallest currency units.

subtotalintegerRequired

Base amount before discounts or tax, in smallest currency units.

taxintegerRequired

Tax amount, in smallest currency units.

totalintegerRequired

Amount due after discounts and tax, in smallest currency units.

off_sessionbooleanRequired

Whether this change was initiated without active customer interaction.

prorated_amountSubscriptionChangeProratedAmountDtoRequired

The total prorated charge for a subscription change, expressed in both settlement and presentment currencies.

currencystringRequired

ISO 4217 settlement currency code, in lowercase.

presentment_currencystringRequired

ISO 4217 presentment currency code, in lowercase.

presentment_prorated_amountintegerRequired

Total prorated charge in smallest presentment currency units, including tax.

prorated_amountintegerRequired

Total prorated charge in smallest settlement currency units, including tax.

proration_behaviorenumRequired

Describes how proration is handled when a subscription change is applied.

Possible enum values

invalid
immediate
Subscription will be updated instantly, and a proration charge will be applied.
next_billing_period
Subscription will be updated at the end of the billing period, no proration will be applied.
none
No proration is applied, subscription is updated instantly.

statusenumRequired

Represents the status of a subscription change.

Possible enum values

invalid
pending_payment
The change is pending payment before it can be applied.
pending_renewal
The change will be applied at the next renewal.
applied
The change has been applied to the subscription.
canceled
The change was canceled and will not be applied.
pending_verification
The change requires a verification code sent to the customer's e-mail.

subscription_idFlakeIdRequired

applied_atstringOptional

prorated_order_idFlakeIdOptional

pending_paymentCheckoutPaymentInfoDtoOptional

Payment outcome information returned after a subscription change triggers an immediate charge.

declinedbooleanRequired

Indicates whether the payment was declined.

statusstringRequired

Status string from the payment provider.

checkout_urlstringOptional

Checkout URL to redirect to for on-session payments.

decline_messagestringOptional

The customer readable decline reason, if the payment was declined.

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

curl -X POST "https://api.paynow.gg/v1/store/tier-groups/{id}/change" \
  -H "Authorization: Customer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "target_product_id": "411486491630370816",
  "verification_code": "string"
}'

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

const paynow = createStorefrontClient({
  storeId: "STORE_ID",
  customerToken: "CUSTOMER_TOKEN",
});

const result = await paynow.tierGroups.updateSubscriptionTierGroup("411486491630370816", {
  target_product_id: "411486491630370816",
  verification_code: "string",
});

import requests

headers = {"Authorization": "Customer TOKEN"}
payload = {
    "target_product_id": "411486491630370816",
    "verification_code": "string",
}
response = requests.post("https://api.paynow.gg/v1/store/tier-groups/{id}/change", headers=headers, json=payload)

Response200

{
  "subscription_change": {
    "created_at": "2024-01-01T00:00:00Z",
    "id": "411486491630370816",
    "lines": [
      {
        "amount": {
          "currency": "string",
          "discount": 0,
          "subtotal": 0,
          "tax": 0,
          "total": 0
        },
        "id": "411486491630370816",
        "is_deleted": true,
        "presentment_amount": {
          "currency": "string",
          "discount": 0,
          "subtotal": 0,
          "tax": 0,
          "total": 0
        },
        "price": 0,
        "product": {
          "custom_variables": {},
          "id": "411486491630370816",
          "name": "string",
          "version_id": "411486491630370816",
          "image_url": "string",
          "selected_gameserver_id": "411486491630370816",
          "pricing_region_id": "string"
        },
        "prorated_amount": 0,
        "prorated_presentment_amount": 0,
        "remaining_minutes": 0,
        "tax_inclusive": true,
        "total_minutes": 0,
        "subscription_line_id": "411486491630370816"
      }
    ],
    "next_billing_amount": {
      "currency": "string",
      "discount": 0,
      "subtotal": 0,
      "tax": 0,
      "total": 0
    },
    "next_billing_presentment_amount": {
      "currency": "string",
      "discount": 0,
      "subtotal": 0,
      "tax": 0,
      "total": 0
    },
    "off_session": true,
    "prorated_amount": {
      "currency": "string",
      "presentment_currency": "string",
      "presentment_prorated_amount": 0,
      "prorated_amount": 0
    },
    "proration_behavior": "invalid",
    "status": "invalid",
    "subscription_id": "411486491630370816",
    "prorated_order_id": "411486491630370816",
    "applied_at": "2024-01-01T00:00:00Z"
  },
  "pending_payment": {
    "declined": true,
    "status": "string",
    "decline_message": "string",
    "checkout_url": "string"
  }
}

Preview update subscription tier group

POSThttps://api.paynow.gg/v1/store/tier-groups/{id}/change/preview

Previews an upgrade or a downgrade an existing subscription tier group. The customer must have an active subscription within this tier group.

Headers

AuthorizationCustomer tokenRequired

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

Path parameters

idFlakeIdRequired

Request body

target_product_idFlakeIdRequired

verification_codestringOptional

A verification code sent to the customer's subscription billing e-mail. Pass this if the `status` field on the `subscription_change` object equals `pending_verification`.

Response

200OKUpdateSubscriptionResponseDto

Response returned after a subscription change is initiated.

Show fields

subscription_changeSubscriptionChangeDtoRequired

A pending or applied change to a subscription.

created_atstringRequired

idFlakeIdRequired

linesSubscriptionChangeLineDto[]Required

A single line item within a subscription change.

amountSubscriptionChangeLineAmountDtoRequired

→ SubscriptionChangeLineAmountDto

idFlakeIdRequired

is_deletedbooleanRequired

Whether this line is being removed by the change.

presentment_amountSubscriptionChangeLineAmountDtoRequired

→ SubscriptionChangeLineAmountDto

priceintegerRequired

Base price in smallest settlement currency units.

productSubscriptionChangeLineProductDtoRequired

→ SubscriptionChangeLineProductDto

prorated_amountintegerRequired

Prorated charge for this line in smallest settlement currency units.

prorated_presentment_amountintegerRequired

Prorated charge for this line in smallest presentment currency units.

remaining_minutesintegerRequired

Minutes remaining in the billing period at the time of change - used to calculate proration.

tax_inclusivebooleanRequired

Whether tax is included in the base price.

total_minutesintegerRequired

Total minutes in the billing period - used to calculate proration.

subscription_line_idFlakeIdOptional

next_billing_amountSubscriptionChangeAmountDtoRequired

Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents).

currencystringRequired

ISO 4217 currency code, in lowercase.

discountintegerRequired

Total discount applied, in smallest currency units.

subtotalintegerRequired

Base amount before discounts or tax, in smallest currency units.

taxintegerRequired

Tax amount, in smallest currency units.

totalintegerRequired

Amount due after discounts and tax, in smallest currency units.

next_billing_presentment_amountSubscriptionChangeAmountDtoRequired

Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents).

currencystringRequired

ISO 4217 currency code, in lowercase.

discountintegerRequired

Total discount applied, in smallest currency units.

subtotalintegerRequired

Base amount before discounts or tax, in smallest currency units.

taxintegerRequired

Tax amount, in smallest currency units.

totalintegerRequired

Amount due after discounts and tax, in smallest currency units.

off_sessionbooleanRequired

Whether this change was initiated without active customer interaction.

prorated_amountSubscriptionChangeProratedAmountDtoRequired

The total prorated charge for a subscription change, expressed in both settlement and presentment currencies.

currencystringRequired

ISO 4217 settlement currency code, in lowercase.

presentment_currencystringRequired

ISO 4217 presentment currency code, in lowercase.

presentment_prorated_amountintegerRequired

Total prorated charge in smallest presentment currency units, including tax.

prorated_amountintegerRequired

Total prorated charge in smallest settlement currency units, including tax.

proration_behaviorenumRequired

Describes how proration is handled when a subscription change is applied.

Possible enum values

invalid
immediate
Subscription will be updated instantly, and a proration charge will be applied.
next_billing_period
Subscription will be updated at the end of the billing period, no proration will be applied.
none
No proration is applied, subscription is updated instantly.

statusenumRequired

Represents the status of a subscription change.

Possible enum values

invalid
pending_payment
The change is pending payment before it can be applied.
pending_renewal
The change will be applied at the next renewal.
applied
The change has been applied to the subscription.
canceled
The change was canceled and will not be applied.
pending_verification
The change requires a verification code sent to the customer's e-mail.

subscription_idFlakeIdRequired

applied_atstringOptional

prorated_order_idFlakeIdOptional

pending_paymentCheckoutPaymentInfoDtoOptional

Payment outcome information returned after a subscription change triggers an immediate charge.

declinedbooleanRequired

Indicates whether the payment was declined.

statusstringRequired

Status string from the payment provider.

checkout_urlstringOptional

Checkout URL to redirect to for on-session payments.

decline_messagestringOptional

The customer readable decline reason, if the payment was declined.

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

curl -X POST "https://api.paynow.gg/v1/store/tier-groups/{id}/change/preview" \
  -H "Authorization: Customer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "target_product_id": "411486491630370816",
  "verification_code": "string"
}'

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

const paynow = createStorefrontClient({
  storeId: "STORE_ID",
  customerToken: "CUSTOMER_TOKEN",
});

const result = await paynow.tierGroups.updateSubscriptionTierGroupPreview("411486491630370816", {
  target_product_id: "411486491630370816",
  verification_code: "string",
});

import requests

headers = {"Authorization": "Customer TOKEN"}
payload = {
    "target_product_id": "411486491630370816",
    "verification_code": "string",
}
response = requests.post("https://api.paynow.gg/v1/store/tier-groups/{id}/change/preview", headers=headers, json=payload)

Response200

{
  "subscription_change": {
    "created_at": "2024-01-01T00:00:00Z",
    "id": "411486491630370816",
    "lines": [
      {
        "amount": {
          "currency": "string",
          "discount": 0,
          "subtotal": 0,
          "tax": 0,
          "total": 0
        },
        "id": "411486491630370816",
        "is_deleted": true,
        "presentment_amount": {
          "currency": "string",
          "discount": 0,
          "subtotal": 0,
          "tax": 0,
          "total": 0
        },
        "price": 0,
        "product": {
          "custom_variables": {},
          "id": "411486491630370816",
          "name": "string",
          "version_id": "411486491630370816",
          "image_url": "string",
          "selected_gameserver_id": "411486491630370816",
          "pricing_region_id": "string"
        },
        "prorated_amount": 0,
        "prorated_presentment_amount": 0,
        "remaining_minutes": 0,
        "tax_inclusive": true,
        "total_minutes": 0,
        "subscription_line_id": "411486491630370816"
      }
    ],
    "next_billing_amount": {
      "currency": "string",
      "discount": 0,
      "subtotal": 0,
      "tax": 0,
      "total": 0
    },
    "next_billing_presentment_amount": {
      "currency": "string",
      "discount": 0,
      "subtotal": 0,
      "tax": 0,
      "total": 0
    },
    "off_session": true,
    "prorated_amount": {
      "currency": "string",
      "presentment_currency": "string",
      "presentment_prorated_amount": 0,
      "prorated_amount": 0
    },
    "proration_behavior": "invalid",
    "status": "invalid",
    "subscription_id": "411486491630370816",
    "prorated_order_id": "411486491630370816",
    "applied_at": "2024-01-01T00:00:00Z"
  },
  "pending_payment": {
    "declined": true,
    "status": "string",
    "decline_message": "string",
    "checkout_url": "string"
  }
}