Getting Started

APIs provided by Stash that your backend can call.

What this section is

Stash-hosted endpoints your backend calls.

This is an ingress integration: your backend calls Stash. Stash hosts and maintains these APIs, while you implement the server-side caller in your backend services.

Call Stash API endpoints from your backend only. Do not expose private API keys in game clients.

Keep credentials on the server, call these endpoints from backend code only, and handle auth, retries, and idempotency in your service layer.

Endpoints

Approve custom login

Approves a pending webshop login from your game server. Send the login code the webshop passed to your game, through the login deep link or a QR code, together with the signed-in player as user; Stash then completes the webshop login as that player. Authenticate the request with an HMAC signature of the request body, or with the deprecated API key. This is a server-side endpoint and must not be called from the game client.

Decline custom login

Tells Stash that the game will not approve this login code, and why. A declined code can no longer be approved. This is a server-side endpoint and should not be called from the client.

Force Logout user

Logs out a user by invalidating their session. This endpoint is typically called when a user signs out of the game or switches to another account.

List plans

Lists all available subscription plans for a shop. By default returns only active plans. Use the status filter to include archived or deprecated plans.

Get plan by code

Retrieves a subscription plan by its code (e.g., 'monthly_premium'). Plan codes are unique within a segment.

Get plan by ID

Retrieves a subscription plan by its unique identifier. Returns full plan details including pricing, billing period, and trial configuration.

Force refresh catalog

Refreshes a web shop's cached catalog so the next time a player opens the shop it reflects the latest catalog from your game backend. Applies only to shops with a real-time catalog integration; for any other integration it is a no-op that still returns success. You rarely need to call it: the catalog already refreshes automatically after web shop purchases and free-gift redemptions, and checkout always revalidates against the server. It is most useful after an in-game purchase (outside the web shop) when you want the catalog view in the Web Shop to update right away. Name the players to refresh in player_ids; when several players need a refresh at the same time, send them in one request rather than one request per player.

Abort offers

Removes offers from every player's web shop at once, for an offer that has to come down before the catalog cache would drop it (for example a wrong price or wrong contents). Each entry names an offer by the identifier your catalog sends: a purchase pack's id (the whole pack, every price point), a purchasable item's product_id (every per-player variant), or a free or non-purchasable item's item_id. Without a version, the abort hides that offer from every player's catalog, whatever your Get Catalog response returns, until you un-abort it; no catalog is fetched again from your server. With a version that is a whole number written only with the ASCII digits 0 to 9 (for example 5), the abort hides the offer with that identifier at that version and at every lower whole-number version, compared by value: an abort of 10 hides 9, an abort of 5 does not hide 10, and 05 reads as 5. With any other version (for example v5, a version with a sign or spaces, or one using digits other than the ASCII 0 to 9), the abort hides only the offer with exactly that version, compared character for character. Cached catalogs that still hold a hidden version are fetched again from your server on each player's next visit. To bring the offer back fixed, re-publish it under the same identifier with a higher version than the one you aborted: it shows as soon as Get Catalog returns it, with no un-abort needed, while a fix re-published at the aborted version or lower stays hidden. An abort with a version never matches an offer sent without a version. An abort with a version expires 7 days after it was made; an abort without a version lasts until un-aborted. Calls are idempotent: an entry that names an abort already active changes nothing. At most 100 entries per call. A purchase already in checkout when the abort lands can still complete, so Confirm Payment remains your last check. Applies only to shops with a real-time catalog integration and offer aborts enabled; any other shop is refused with FAILED_PRECONDITION.

List offer aborts

Lists every active abort for your shop, including aborts made in Stash Studio, newest first. An abort with a version that has expired is not listed.

Un-abort offers

Removes the aborts each entry names, so those offers show again on each player's next catalog read whenever your Get Catalog response returns them, with no catalog fetched again from your server. An entry removes exactly one abort: an identifier alone removes the abort without a version, and an identifier with a version removes the abort for that version, written as the abort lists it. Versions that another active abort of the same offer still covers stay hidden: removing the abort of 7 while an abort of 5 is active shows versions 6 and 7 again and keeps 5 and lower hidden. It also removes aborts made in Stash Studio. An entry that names no active abort changes nothing. At most 100 entries per call.

Generate Checkout

Generates a quick payment URL for server-side operations. This endpoint is used internally for creating payment links with user information.

Generate authenticated URL

Generates an authenticated webshop URL for a player that signs them in when opened. target selects the page it opens: DEFAULT or ROOT for the webshop's root page, HOME for the home page, STORE for the store page, LOYALTY for the loyalty club page, or DAILY_STREAK for the daily streak page. Authenticate the request with an HMAC signature of the request body, or with the deprecated API key. This is a server-side endpoint and must not be called from the game client.

Get payment event by ID

Retrieves payment details by ID. Returns information about items, pricing, and payment status. This is a server-side endpoint and should not be called from the client.

Get prices

Retrieves uploaded pricing sheet data for the shop associated with the API key, filtered by region. Returns paginated price entries.

Convert prices

Fetches pre-converted prices from the price sheet for the given destination country, applies tax based on region, and optionally applies custom rounding. Returns final prices in minor units and locale-formatted display strings.

Get maintenance mode

Returns whether your web shop is in maintenance mode and, while it is, since when. Each shop may make up to 60 calls every 60 seconds; above that it returns 429 with a RetryInfo detail giving how long to wait. This is a server-side endpoint and should not be called from the client.

Set maintenance mode

Switches your web shop into or out of maintenance mode. While it is on, players see the web shop's maintenance screen instead of the shop: new visits and sign-ins get the maintenance screen once the setting reaches the web shop, normally within about 30 seconds. A page a player already has open switches to the maintenance screen when it next reloads. Players stay signed in. Send enabled true to switch it on and false to switch it off; a request without enabled is refused with 400. The call is idempotent: switching on a shop that is already in maintenance mode succeeds and keeps the original since time, and switching off a shop that is not in maintenance mode succeeds and changes nothing. The response returns the resulting state. Each shop may make up to 10 calls every 60 seconds; above that it returns 429 with a RetryInfo detail giving how long to wait. This is a server-side endpoint and should not be called from the client.

Get user preferences

Retrieves the payment channel preference for a specific user. Returns 404 NotFound if no preference is set.

Set user preferences

Creates or updates the payment channel preference for a user. This is a server-side endpoint and should not be called from the client.

List subscriptions

Query subscriptions by player and optionally filter by status. Returns all matching subscriptions for the specified external_account_id.

Get subscription by ID

Retrieves a subscription by its unique identifier. Returns the full subscription object including status, billing period, and dates.

Update subscription

Applies one change to a subscription. free_period grants free billing periods that start when the current paid period ends: the subscriber keeps access, is not charged at the next renewal date, and billing resumes at the plan's normal price when the free period ends. A scheduled cancellation is reversed. Rejections return FAILED_PRECONDITION with reason SUBSCRIPTION_NOT_ELIGIBLE, FREE_PERIOD_ALREADY_ACTIVE or RENEWAL_IN_PROGRESS. Reusing an idempotency_key with different parameters returns ALREADY_EXISTS.

Cancel subscription

Cancels a subscription. By default, access continues until the end of the current billing period (cancel_at_period_end=true). A subscription.canceled webhook is sent and the returned subscription has status 'canceled'. For past_due subscriptions, cancellation is immediate: a single subscription.expired webhook is sent and the returned subscription has status 'expired'.

Get payments by subscription ID

Retrieves payments associated with a subscription with pagination support. Returns a list of payment objects including payment ID, amount, currency, a succeeded indicator, and timestamps. Use the `next_page_token` from the response to fetch the next page.

Reactivate subscription

Reactivates a previously canceled subscription. Only valid before the subscription has expired.

Create a subscription checkout link

Creates a checkout link for purchasing a subscription plan. The link can be shared with users to complete their subscription purchase.

Create a subscription change checkout link

Creates a checkout link for upgrading an existing subscription to a new plan. Only subscriptions in a `active`, `trialing`, or `cancelled` (still within paid period before expiration) state are eligible for upgrades.

Get loyalty program configuration

Retrieves the shop's active loyalty campaign configuration: its tiers (ordered by starting points) and milestones (ordered by points needed). Returns NOT_FOUND when the shop has no active loyalty campaign.

Get loyalty configuration

Retrieves the shop's loyalty configuration in the shape UpdateLoyaltyConfig accepts: display settings, bonus definitions, reward products with their status, every campaign (season) with its status, and the spend conversion table with the rate derived per currency. Product rewards are returned by SKU. Use it to verify a sync. This method accepts only the versioned x-stash-hmac-signature header, signed over an empty body; the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. Errors, by the HTTP status a REST caller receives and its gRPC status: 401 UNAUTHENTICATED when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop; fix the signing, because resending it unchanged does not help. 404 NOT_FOUND for an unknown shop or a shop with no loyalty program; it does not change on a retry. 501 UNIMPLEMENTED when the loyalty configuration API is not available; it does not change on a retry. 500 INTERNAL when Stash hits an internal error, for example reading the shop's loyalty configuration; reading is safe to repeat, so retry with backoff.

Configure a loyalty season

Creates or updates one loyalty campaign (season) together with the shop-level display settings, bonus definitions and reward products it depends on, optionally sets or removes the program-level spend conversion table, and optionally activates the program. The campaign id is the upsert key: an existing id updates that season, a new id creates one. The request describes the whole season it names, so a tier or milestone omitted from it is removed from that season; bonuses and reward products are created or updated by id or SKU and never removed. Draft and scheduled seasons accept every change. An active season accepts names, descriptions, images, milestone rewards, tier earn rates and a new end date; thresholds, adding or removing tiers or milestones, the start date and reset rules are refused with FAILED_PRECONDITION listing the fields. Ended seasons are read-only. This method accepts only the versioned x-stash-hmac-signature header, signed over the request body exactly as sent; the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. Applying is idempotent, so resending the same request is safe. Errors, by the HTTP status a REST caller receives and its gRPC status. Two of them share HTTP 400; a REST caller tells them apart by the code in the error body, 3 for INVALID_ARGUMENT and 9 for FAILED_PRECONDITION. 400 INVALID_ARGUMENT (code 3) with per-field violations when validation fails, including a spend conversion price whose rate against the US dollar is more than 3 times above or below the market rate, which the violation on that price names; fix the request, correcting the price, because resending it unchanged does not help. 400 FAILED_PRECONDITION (code 9) when the request cannot apply to the program as it stands, with the reason in the message: for example a locked field of an active season changes (the message lists the fields), the shop has no loyalty program and activate is not set, or the shop's loyalty program is bound to more than one shop; resend only once that changes, or as is when the message says to re-send the request. 401 UNAUTHENTICATED when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop; fix the signing. 403 PERMISSION_DENIED when the shop is not enabled for configuration writes; it does not change on a retry. 404 NOT_FOUND for an unknown shop; it does not change on a retry. 409 ABORTED when another update for the shop is in progress; resend the same request after a short wait, which is safe because applying is idempotent. 501 UNIMPLEMENTED when the loyalty configuration API is not available; it does not change on a retry. 500 INTERNAL when Stash hits an internal error, for example reading or writing the shop's loyalty configuration; resend the same request with backoff. 503 UNAVAILABLE when the request has a spend conversion price in a currency other than USD and Stash has no market rates loaded, for example shortly after a restart; nothing is written, and resending the same request with backoff is safe because applying is idempotent.

Get a player's loyalty standing

Retrieves a single player's loyalty standing (points balance, current tier, distance to the next tier and milestone, and effective points multiplier) for the shop's active loyalty campaign. Returns NOT_FOUND when the shop has no active loyalty campaign.

Refresh localizations

Asks Stash to refresh the shop's localizations from its enabled localization source, for example after the source file changes. The request body is the empty JSON object {}. This method accepts only the versioned x-stash-hmac-signature header, signed over the request body exactly as sent ({}); the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. The shop in the signature header must equal the shop_id in the path. A successful response means the refresh is durably queued, not that the import has completed or that the storefront shows the result. Repeated calls are safe, so retry after a 500, a 503 or a timeout with a fresh timestamp and signature. Errors, by the HTTP status a REST caller receives and its gRPC status. Two of them share HTTP 400; a REST caller tells them apart by the code in the error body, 3 for INVALID_ARGUMENT and 9 for FAILED_PRECONDITION. 400 INVALID_ARGUMENT (code 3) when the request is malformed, for example a body that is not valid JSON; fix the request, because resending it unchanged does not help. 400 FAILED_PRECONDITION (code 9) when the shop has no enabled localization source; retrying does not help until the source is set up and enabled. 401 UNAUTHENTICATED when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop or one Stash does not know; fix the signing, because resending it unchanged does not help. 500 INTERNAL when Stash hits an internal error, for example reading the shop's localization settings; retry with backoff. 503 UNAVAILABLE when the refresh could not be queued; retry with backoff.

List report files

Returns one entry for each UTC day in [start_date, end_date] that has a file, in date order, each with a signed GET link to that day's file. A day with no transactions still has a file, with no rows. A day with no entry is a day the export has not written yet, such as the current UTC day or a day whose export is late; it does not mean the day had no transactions, so call again later for that day. Days before first_date never get a file, because the shop's export of that type and format started on first_date. A shop that has no file of the requested type and format on any day gets FAILED_PRECONDITION instead. Stash turns a shop's export on, and it writes the first file, before the partner is told that the report is available; so this error means the report is not available for the shop yet: do not retry, contact Stash. The files use the same columns as the transaction reports in Stash Studio. Each row is one event: a payment, a refund or a dispute step. A later refund or dispute step is a new row on its own day; it does not change the payment's row. The record_id column is a stable ID of the event: the same event has the same record_id in every file. Use it to remove rows that two pulls share, and keep the row from the later pull. Columns are added only at the end, and a column is renamed or removed only with advance notice, so read the files by column name, not by position. A SETTLED day that is not final can still change; pull it again until is_final is true. SETTLED days become final together with their UTC calendar month, when Stash closes the month, usually 1 to 5 days after it ends. CHARGE days are never final, because their rows change while their charges settle, so do not wait for is_final on a CHARGE day. Stash gives no stop signal for a CHARGE day: follow it for as long as you need its unsettled rows, and use SETTLED for figures that become final. To know when to download a day again, compare its content_hash with the copy you hold: every change to the file's bytes gives a new content_hash, and the same bytes always give the same content_hash. as_of is the time of the data snapshot that each file was written from. Every link is valid until download_url_expires_at, 15 minutes after the response; call again for fresh links. This method accepts only the versioned x-stash-hmac-signature header, signed over the request body exactly as sent; the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. The shop in the signature header must equal the shop_id in the path. Repeated calls are safe, so retry after UNAVAILABLE or a timeout with a fresh timestamp and signature. Returns HTTP 401 (UNAUTHENTICATED) when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop or one Stash does not know; HTTP 400 (INVALID_ARGUMENT) when report_type or report_format is unspecified or unknown, a date is missing or is not YYYY-MM-DD, end_date is before start_date, or the range is longer than 31 days; HTTP 400 (FAILED_PRECONDITION) when the shop has no file of the requested type and format on any day; and HTTP 503 (UNAVAILABLE) when the files could not be listed, in which case retry. The two HTTP 400 cases differ only by the code in the response body: 3 for INVALID_ARGUMENT, 9 for FAILED_PRECONDITION. Do not retry UNAUTHENTICATED or INVALID_ARGUMENT unchanged: correct the signature or the request first, then send it again with a fresh timestamp and signature.

How is this guide?

Abort offers POST

Removes offers from every player's web shop at once, for an offer that has to come down before the catalog cache would drop it (for example a wrong price or wrong contents). Each entry names an offer by the identifier your catalog sends: a purchase pack's id (the whole pack, every price point), a purchasable item's product_id (every per-player variant), or a free or non-purchasable item's item_id. Without a version, the abort hides that offer from every player's catalog, whatever your Get Catalog response returns, until you un-abort it; no catalog is fetched again from your server. With a version that is a whole number written only with the ASCII digits 0 to 9 (for example 5), the abort hides the offer with that identifier at that version and at every lower whole-number version, compared by value: an abort of 10 hides 9, an abort of 5 does not hide 10, and 05 reads as 5. With any other version (for example v5, a version with a sign or spaces, or one using digits other than the ASCII 0 to 9), the abort hides only the offer with exactly that version, compared character for character. Cached catalogs that still hold a hidden version are fetched again from your server on each player's next visit. To bring the offer back fixed, re-publish it under the same identifier with a higher version than the one you aborted: it shows as soon as Get Catalog returns it, with no un-abort needed, while a fix re-published at the aborted version or lower stays hidden. An abort with a version never matches an offer sent without a version. An abort with a version expires 7 days after it was made; an abort without a version lasts until un-aborted. Calls are idempotent: an entry that names an abort already active changes nothing. At most 100 entries per call. A purchase already in checkout when the abort lands can still complete, so Confirm Payment remains your last check. Applies only to shops with a real-time catalog integration and offer aborts enabled; any other shop is refused with FAILED_PRECONDITION.