# Tier Groups

## Get customer tier groups

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

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"tier-groups"}],"security":[{},{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"CustomerTierGroupDto":{"required":["active_product_id","currency","next_billing_amount","next_billing_presentment_amount","next_renewal_at","presentment_currency","tier_group_id"],"type":"object","properties":{"tier_group_id":{"$ref":"#/components/schemas/FlakeId"},"active_product_id":{"$ref":"#/components/schemas/FlakeId"},"pending_change_product_id":{"$ref":"#/components/schemas/FlakeId"},"next_renewal_at":{"type":"string","description":"The date and time of the next subscription renewal for this tier group.","format":"date-time"},"next_billing_amount":{"type":"integer","description":"The next billing amount in the smallest currency unit (e.g., cents) in the settlement currency.","format":"int64"},"next_billing_presentment_amount":{"type":"integer","description":"The next billing amount in the smallest currency unit (e.g., cents) in the customer-facing presentment currency.","format":"int64"},"currency":{"type":"string","description":"The settlement currency code (e.g., \"usd\")."},"presentment_currency":{"type":"string","description":"The customer-facing presentment currency code (e.g., \"eur\")."}},"additionalProperties":false},"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/tier-groups":{"get":{"tags":["tier-groups"],"summary":"Get customer tier groups","description":"Retrieves tier group state for a logged in customer. Returns an empty array if not logged in.","operationId":"StorefrontTierGroups_GetCustomerTierGroups","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CustomerTierGroupDto"}}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```

## Update subscription tier group

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

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"tier-groups"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"UpdateSubscriptionTierRequestDto":{"required":["target_product_id"],"type":"object","properties":{"target_product_id":{"$ref":"#/components/schemas/FlakeId"},"verification_code":{"type":["null","string"],"description":"A verification code sent to the customer's subscription billing e-mail.\nPass this if the `status` field on the `subscription_change` object equals `pending_verification`."}},"additionalProperties":false},"UpdateSubscriptionResponseDto":{"required":["subscription_change"],"type":"object","properties":{"subscription_change":{"$ref":"#/components/schemas/SubscriptionChangeDto"},"pending_payment":{"$ref":"#/components/schemas/CheckoutPaymentInfoDto"}},"additionalProperties":false,"description":"Response returned after a subscription change is initiated."},"SubscriptionChangeDto":{"required":["created_at","id","lines","next_billing_amount","next_billing_presentment_amount","off_session","prorated_amount","proration_behavior","status","subscription_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"subscription_id":{"$ref":"#/components/schemas/FlakeId"},"prorated_order_id":{"$ref":"#/components/schemas/FlakeId"},"status":{"$ref":"#/components/schemas/SubscriptionChangeStatusDto"},"proration_behavior":{"$ref":"#/components/schemas/ProrationBehaviorDto"},"off_session":{"type":"boolean","description":"Whether this change was initiated without active customer interaction."},"prorated_amount":{"$ref":"#/components/schemas/SubscriptionChangeProratedAmountDto"},"created_at":{"type":"string","format":"date-time"},"applied_at":{"type":["null","string"],"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionChangeLineDto"}},"next_billing_amount":{"$ref":"#/components/schemas/SubscriptionChangeAmountDto"},"next_billing_presentment_amount":{"$ref":"#/components/schemas/SubscriptionChangeAmountDto"}},"additionalProperties":false,"description":"A pending or applied change to a subscription."},"SubscriptionChangeStatusDto":{"enum":["invalid","pending_payment","pending_renewal","applied","canceled","pending_verification"],"type":"string","description":"Represents the status of a subscription change."},"ProrationBehaviorDto":{"enum":["invalid","immediate","next_billing_period","none"],"type":"string","description":"Describes how proration is handled when a subscription change is applied."},"SubscriptionChangeProratedAmountDto":{"required":["currency","presentment_currency","presentment_prorated_amount","prorated_amount"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 settlement currency code, in lowercase."},"prorated_amount":{"type":"integer","description":"Total prorated charge in smallest settlement currency units, including tax.","format":"int64"},"presentment_currency":{"type":"string","description":"ISO 4217 presentment currency code, in lowercase."},"presentment_prorated_amount":{"type":"integer","description":"Total prorated charge in smallest presentment currency units, including tax.","format":"int64"}},"additionalProperties":false,"description":"The total prorated charge for a subscription change, expressed in both settlement and presentment currencies."},"SubscriptionChangeLineDto":{"required":["amount","id","is_deleted","presentment_amount","price","product","prorated_amount","prorated_presentment_amount","remaining_minutes","tax_inclusive","total_minutes"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"subscription_line_id":{"$ref":"#/components/schemas/FlakeId"},"is_deleted":{"type":"boolean","description":"Whether this line is being removed by the change."},"tax_inclusive":{"type":"boolean","description":"Whether tax is included in the base price."},"price":{"type":"integer","description":"Base price in smallest settlement currency units.","format":"int64"},"product":{"$ref":"#/components/schemas/SubscriptionChangeLineProductDto"},"amount":{"$ref":"#/components/schemas/SubscriptionChangeLineAmountDto"},"presentment_amount":{"$ref":"#/components/schemas/SubscriptionChangeLineAmountDto"},"prorated_amount":{"type":"integer","description":"Prorated charge for this line in smallest settlement currency units.","format":"int64"},"prorated_presentment_amount":{"type":"integer","description":"Prorated charge for this line in smallest presentment currency units.","format":"int64"},"remaining_minutes":{"type":"integer","description":"Minutes remaining in the billing period at the time of change - used to calculate proration.","format":"int64"},"total_minutes":{"type":"integer","description":"Total minutes in the billing period - used to calculate proration.","format":"int64"}},"additionalProperties":false,"description":"A single line item within a subscription change."},"SubscriptionChangeLineProductDto":{"required":["custom_variables","id","name","version_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"version_id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"Display name of the product."},"image_url":{"type":["null","string"],"description":"URL of the product image, if set."},"selected_gameserver_id":{"$ref":"#/components/schemas/FlakeId"},"pricing_region_id":{"type":["null","string"],"description":"The pricing region used to determine the price, if applicable."},"custom_variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomVariableLineItemDto"},"description":"Custom variables set on this line item, keyed by variable identifier."}},"additionalProperties":false,"description":"The product associated with a subscription change line."},"CustomVariableLineItemDto":{"required":["description","id","identifier","name","price","value"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"identifier":{"type":"string","description":"The identifier used to reference this custom variable (e.g., \"color\", \"size\")."},"name":{"type":"string","description":"The display name of the custom variable shown to users."},"description":{"type":"string","description":"A detailed description of what this custom variable represents."},"price":{"type":"integer","description":"The price associated with this custom variable in the smallest currency unit (e.g., cents).","format":"int64"},"value":{"type":"string","description":"The selected value for this custom variable."}},"additionalProperties":false},"SubscriptionChangeLineAmountDto":{"required":["currency","discount","subtotal","tax","total"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code in lowercase."},"subtotal":{"type":"integer","description":"Base amount before discounts or tax, in smallest currency units.","format":"int64"},"discount":{"type":"integer","description":"Total discount applied, in smallest currency units.","format":"int64"},"tax":{"type":"integer","description":"Tax amount, in smallest currency units.","format":"int64"},"total":{"type":"integer","description":"Amount due after discounts and tax, in smallest currency units.","format":"int64"}},"additionalProperties":false,"description":"Pricing breakdown for a single subscription change line, in the smallest units of the given currency (e.g. cents)."},"SubscriptionChangeAmountDto":{"required":["currency","discount","subtotal","tax","total"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code, in lowercase."},"subtotal":{"type":"integer","description":"Base amount before discounts or tax, in smallest currency units.","format":"int64"},"discount":{"type":"integer","description":"Total discount applied, in smallest currency units.","format":"int64"},"tax":{"type":"integer","description":"Tax amount, in smallest currency units.","format":"int64"},"total":{"type":"integer","description":"Amount due after discounts and tax, in smallest currency units.","format":"int64"}},"additionalProperties":false,"description":"Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents)."},"CheckoutPaymentInfoDto":{"required":["declined","status"],"type":"object","properties":{"status":{"type":"string","description":"Status string from the payment provider."},"declined":{"type":"boolean","description":"Indicates whether the payment was declined."},"decline_message":{"type":["null","string"],"description":"The customer readable decline reason, if the payment was declined."},"checkout_url":{"type":["null","string"],"description":"Checkout URL to redirect to for on-session payments."}},"additionalProperties":false,"description":"Payment outcome information returned after a subscription change triggers an immediate charge."},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/tier-groups/{id}/change":{"post":{"tags":["tier-groups"],"summary":"Update subscription tier group","description":"Upgrades or downgrades an existing subscription tier group. The customer must have an active subscription within this tier group.","operationId":"StorefrontTierGroups_UpdateSubscriptionTierGroup","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/FlakeId"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionResponseDto"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```

## Preview update subscription tier group

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

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"tier-groups"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"UpdateSubscriptionTierRequestDto":{"required":["target_product_id"],"type":"object","properties":{"target_product_id":{"$ref":"#/components/schemas/FlakeId"},"verification_code":{"type":["null","string"],"description":"A verification code sent to the customer's subscription billing e-mail.\nPass this if the `status` field on the `subscription_change` object equals `pending_verification`."}},"additionalProperties":false},"UpdateSubscriptionResponseDto":{"required":["subscription_change"],"type":"object","properties":{"subscription_change":{"$ref":"#/components/schemas/SubscriptionChangeDto"},"pending_payment":{"$ref":"#/components/schemas/CheckoutPaymentInfoDto"}},"additionalProperties":false,"description":"Response returned after a subscription change is initiated."},"SubscriptionChangeDto":{"required":["created_at","id","lines","next_billing_amount","next_billing_presentment_amount","off_session","prorated_amount","proration_behavior","status","subscription_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"subscription_id":{"$ref":"#/components/schemas/FlakeId"},"prorated_order_id":{"$ref":"#/components/schemas/FlakeId"},"status":{"$ref":"#/components/schemas/SubscriptionChangeStatusDto"},"proration_behavior":{"$ref":"#/components/schemas/ProrationBehaviorDto"},"off_session":{"type":"boolean","description":"Whether this change was initiated without active customer interaction."},"prorated_amount":{"$ref":"#/components/schemas/SubscriptionChangeProratedAmountDto"},"created_at":{"type":"string","format":"date-time"},"applied_at":{"type":["null","string"],"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionChangeLineDto"}},"next_billing_amount":{"$ref":"#/components/schemas/SubscriptionChangeAmountDto"},"next_billing_presentment_amount":{"$ref":"#/components/schemas/SubscriptionChangeAmountDto"}},"additionalProperties":false,"description":"A pending or applied change to a subscription."},"SubscriptionChangeStatusDto":{"enum":["invalid","pending_payment","pending_renewal","applied","canceled","pending_verification"],"type":"string","description":"Represents the status of a subscription change."},"ProrationBehaviorDto":{"enum":["invalid","immediate","next_billing_period","none"],"type":"string","description":"Describes how proration is handled when a subscription change is applied."},"SubscriptionChangeProratedAmountDto":{"required":["currency","presentment_currency","presentment_prorated_amount","prorated_amount"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 settlement currency code, in lowercase."},"prorated_amount":{"type":"integer","description":"Total prorated charge in smallest settlement currency units, including tax.","format":"int64"},"presentment_currency":{"type":"string","description":"ISO 4217 presentment currency code, in lowercase."},"presentment_prorated_amount":{"type":"integer","description":"Total prorated charge in smallest presentment currency units, including tax.","format":"int64"}},"additionalProperties":false,"description":"The total prorated charge for a subscription change, expressed in both settlement and presentment currencies."},"SubscriptionChangeLineDto":{"required":["amount","id","is_deleted","presentment_amount","price","product","prorated_amount","prorated_presentment_amount","remaining_minutes","tax_inclusive","total_minutes"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"subscription_line_id":{"$ref":"#/components/schemas/FlakeId"},"is_deleted":{"type":"boolean","description":"Whether this line is being removed by the change."},"tax_inclusive":{"type":"boolean","description":"Whether tax is included in the base price."},"price":{"type":"integer","description":"Base price in smallest settlement currency units.","format":"int64"},"product":{"$ref":"#/components/schemas/SubscriptionChangeLineProductDto"},"amount":{"$ref":"#/components/schemas/SubscriptionChangeLineAmountDto"},"presentment_amount":{"$ref":"#/components/schemas/SubscriptionChangeLineAmountDto"},"prorated_amount":{"type":"integer","description":"Prorated charge for this line in smallest settlement currency units.","format":"int64"},"prorated_presentment_amount":{"type":"integer","description":"Prorated charge for this line in smallest presentment currency units.","format":"int64"},"remaining_minutes":{"type":"integer","description":"Minutes remaining in the billing period at the time of change - used to calculate proration.","format":"int64"},"total_minutes":{"type":"integer","description":"Total minutes in the billing period - used to calculate proration.","format":"int64"}},"additionalProperties":false,"description":"A single line item within a subscription change."},"SubscriptionChangeLineProductDto":{"required":["custom_variables","id","name","version_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"version_id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"Display name of the product."},"image_url":{"type":["null","string"],"description":"URL of the product image, if set."},"selected_gameserver_id":{"$ref":"#/components/schemas/FlakeId"},"pricing_region_id":{"type":["null","string"],"description":"The pricing region used to determine the price, if applicable."},"custom_variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomVariableLineItemDto"},"description":"Custom variables set on this line item, keyed by variable identifier."}},"additionalProperties":false,"description":"The product associated with a subscription change line."},"CustomVariableLineItemDto":{"required":["description","id","identifier","name","price","value"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"identifier":{"type":"string","description":"The identifier used to reference this custom variable (e.g., \"color\", \"size\")."},"name":{"type":"string","description":"The display name of the custom variable shown to users."},"description":{"type":"string","description":"A detailed description of what this custom variable represents."},"price":{"type":"integer","description":"The price associated with this custom variable in the smallest currency unit (e.g., cents).","format":"int64"},"value":{"type":"string","description":"The selected value for this custom variable."}},"additionalProperties":false},"SubscriptionChangeLineAmountDto":{"required":["currency","discount","subtotal","tax","total"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code in lowercase."},"subtotal":{"type":"integer","description":"Base amount before discounts or tax, in smallest currency units.","format":"int64"},"discount":{"type":"integer","description":"Total discount applied, in smallest currency units.","format":"int64"},"tax":{"type":"integer","description":"Tax amount, in smallest currency units.","format":"int64"},"total":{"type":"integer","description":"Amount due after discounts and tax, in smallest currency units.","format":"int64"}},"additionalProperties":false,"description":"Pricing breakdown for a single subscription change line, in the smallest units of the given currency (e.g. cents)."},"SubscriptionChangeAmountDto":{"required":["currency","discount","subtotal","tax","total"],"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code, in lowercase."},"subtotal":{"type":"integer","description":"Base amount before discounts or tax, in smallest currency units.","format":"int64"},"discount":{"type":"integer","description":"Total discount applied, in smallest currency units.","format":"int64"},"tax":{"type":"integer","description":"Tax amount, in smallest currency units.","format":"int64"},"total":{"type":"integer","description":"Amount due after discounts and tax, in smallest currency units.","format":"int64"}},"additionalProperties":false,"description":"Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents)."},"CheckoutPaymentInfoDto":{"required":["declined","status"],"type":"object","properties":{"status":{"type":"string","description":"Status string from the payment provider."},"declined":{"type":"boolean","description":"Indicates whether the payment was declined."},"decline_message":{"type":["null","string"],"description":"The customer readable decline reason, if the payment was declined."},"checkout_url":{"type":["null","string"],"description":"Checkout URL to redirect to for on-session payments."}},"additionalProperties":false,"description":"Payment outcome information returned after a subscription change triggers an immediate charge."},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/tier-groups/{id}/change/preview":{"post":{"tags":["tier-groups"],"summary":"Preview update subscription tier group","description":"Previews an upgrade or a downgrade an existing subscription tier group. The customer must have an active subscription within this tier group.","operationId":"StorefrontTierGroups_UpdateSubscriptionTierGroupPreview","parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/FlakeId"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionTierRequestDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionResponseDto"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paynow.gg/storefront-headless/storefront-api/tier-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.