Integrating Subscriptions

This guide explains how to integrate Stash Subscriptions into your game, from displaying available plans to handling subscription lifecycle events.

Integration overview

Display available plans

Fetch available subscription plans using the List Plans endpoint.

curl -X GET "https://api.stash.gg/sdk/plans" \
  -H "X-Stash-Api-Key: YOUR_API_KEY"

Plan response

{
  "plans": [
    {
      "id": "plan_abc123",
      "code": "monthly_premium",
      "name": "Premium Monthly",
      "description": "Access to all premium features",
      "billingPeriodValue": 1,
      "billingPeriodUnit": "month",
      "prices": [
        { "currency": "USD", "amountCents": 999 },
        { "currency": "EUR", "amountCents": 899 }
      ],
      "trialPeriodValue": 7,
      "trialPeriodUnit": "day",
      "status": "active"
    }
  ]
}

Display these plans in your game UI, showing the name, description, price, and trial period (if any).

Create subscription checkout

When a player selects a plan, create a subscription checkout link using the Create Subscription Checkout Link endpoint.

curl -X POST "https://api.stash.gg/sdk/subscriptions/checkout-links" \
  -H "X-Stash-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_abc123",
    "user": {
      "id": "player_123"
    },
    "currency": "USD"
  }'

The response includes a checkout URL to present to the player:

{
  "url": "https://checkout.stash.gg/subscribe/abc123",
  "id": "checkout_abc123"
}

Initial payment discounts

You can customize the first payment amount using the initialPayment field. This is useful for offering promotional pricing, trials with reduced cost, or custom first-month deals.

Discount by fixed amount:

curl -X POST "https://api.stash.gg/sdk/subscriptions/checkout-links" \
  -H "X-Stash-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_abc123",
    "user": {
      "id": "player_123"
    },
    "currency": "USD",
    "initialPayment": {
      "discount": {
        "amountOffCents": 500
      }
    }
  }'

Discount by percentage:

curl -X POST "https://api.stash.gg/sdk/subscriptions/checkout-links" \
  -H "X-Stash-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_abc123",
    "user": {
      "id": "player_123"
    },
    "currency": "USD",
    "initialPayment": {
      "discount": {
        "percentOff": 50
      }
    }
  }'

Custom initial amount:

curl -X POST "https://api.stash.gg/sdk/subscriptions/checkout-links" \
  -H "X-Stash-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_abc123",
    "user": {
      "id": "player_123"
    },
    "currency": "USD",
    "initialPayment": {
      "customAmountCents": 199
    }
  }'

After the player completes the checkout, Stash creates the subscription and sends a subscription.created webhook to your backend.

Subscription change (upgrade) checkout

To change an existing subscription (plan upgrade and/or payment method), create a subscription change checkout link with Create a subscription change checkout link:

curl -X POST "https://api.stash.gg/sdk/subscriptions/sub_xyz789/change-checkout-links" \
  -H "X-Stash-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newPlan": "plan_higher_tier"
  }'

The response includes url and id (for example a checkout URL like https://checkout.stash.gg/subscription/change/{checkoutLinkId}). At least one of newPlan or updatePaymentMethod must be set; see the API reference for optional fields such as billingAnchor, initialPayment, and paymentMethod.

Eligibility: active, trialing, or canceled with current_period_end still in the future (canceled but still in the paid window). If the subscription is canceled after that paid window, create a new subscription with Create Subscription Checkout Link instead.

Behavior: Creating the link only validates eligibility and stores the link—it does not reactivate a canceled subscription or apply the plan change. If the buyer abandons checkout, the subscription stays as-is (for example, still canceled). When checkout completes successfully, Stash applies the upgrade and, if the subscription was canceled-but-not-expired, reactivates it as part of that update.

See the API reference for full request and response fields.

Handle webhooks

Set up a webhook endpoint to receive subscription lifecycle events. See the Webhooks guide for general webhook setup.

Subscription webhook events

Webhook payload (v2)

Subscription webhooks use a v2 payload format:

{
  "type": "subscription.created",
  "data": {
    "id": "sub_xyz789",
    "external_account_id": "player_123",
    "plan_id": "plan_abc123",
    "status": "active",
    "period": {
      "value": 1,
      "unit": "month"
    },
    "trial_end": "2024-02-01T00:00:00Z",
    "access_end_date": "2024-03-01T00:00:00Z",
    "current_period_end": "2024-03-01T00:00:00Z",
    "next_billing_date": "2024-03-01T00:00:00Z",
    "cancel_at_period_end": false,
    "canceled_at": null,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Handling subscription.created

When you receive subscription.created:

1. Store the subscription ID and player mapping
2. Grant the player access to subscription benefits
3. Update your game's subscription UI

app.post('/webhooks/stash', (req, res) => {
  const { type, data } = req.body;

  if (type === 'subscription.created') {
    // Grant subscription benefits to player
    await grantSubscriptionAccess(data.external_account_id, data.plan_id);

    // Store subscription for later reference
    await saveSubscription(data);
  }

  res.status(200).send('OK');
});

Handling subscription.expired

When you receive subscription.expired:

1. Revoke the player's subscription benefits
2. Update your game's subscription UI
3. Optionally prompt the player to resubscribe

Payment webhook events

Payment webhooks (payment.succeeded, payment.failed, payment.refunded, dispute.opened, dispute.closed) use the same v2 payload format as subscription events. See Payment Events in the webhook list for event types and payload schemas.

Manage subscriptions

Check subscription status

Use List Subscriptions to check a player's active subscriptions:

curl -X GET "https://api.stash.gg/sdk/subscriptions?external_account_id=player_123" \
  -H "X-Stash-Api-Key: YOUR_API_KEY"

Filter by status to find only active subscriptions:

curl -X GET "https://api.stash.gg/sdk/subscriptions?external_account_id=player_123&status=active" \
  -H "X-Stash-Api-Key: YOUR_API_KEY"

Cancel a subscription

Allow players to cancel their subscription using Cancel Subscription:

curl -X POST "https://api.stash.gg/sdk/subscriptions/sub_xyz789/cancel" \
  -H "X-Stash-Api-Key: YOUR_API_KEY"

After cancellation:

• cancel_at_period_end becomes true
• Player keeps access until current_period_end
• Webhook subscription.canceled is sent

Reactivate a subscription

If a player changes their mind before the period ends, reactivate with Reactivate Subscription:

curl -X POST "https://api.stash.gg/sdk/subscriptions/sub_xyz789/reactivate" \
  -H "X-Stash-Api-Key: YOUR_API_KEY"

Testing renewal scenarios

In the test environment, Stash supports simulation cards that return scripted payment outcomes for subscription initial payments and renewals. Use these cards to exercise grace periods, retry recovery, declines, and system errors without waiting on a real PSP.

How simulation works

Each simulation card defines a sequence of outcomes keyed by billing period and retry attempt:

Within each period, retry count tracks payment attempts during that billing cycle:

Simulation test cards

Testing payment declines and reasons

The simulation cards above exercise subscription lifecycle transitions but do not produce payment.* webhooks. To test the payment-failure webhooks themselves, and the reason they carry, use the decline cards below. Each is declined with a specific reason, and Stash delivers a payment.failed webhook (and, when a renewal on an existing subscription is declined, a subscription.payment_failed webhook) whose reason field is set to the value shown.

Enter any future expiration date (for example, 03/30) and any valid CVC — the card number alone decides the outcome.

To test card_expired, use any card number above with an expiration date in the past; the payment is declined as an expired card and reason is card_expired. A failed first-time payment delivers payment.failed only; subscription.payment_failed is sent when a renewal on an existing subscription fails.

Best practices

Validate access server-side

Always validate subscription access on your game server, not just the client. Check the subscription status and access_end_date before granting premium features.

Handle payment failures gracefully

When you receive subscription.payment_failed, don't immediately revoke access. The player is in a grace period and Stash is retrying the payment. Only revoke access when you receive subscription.expired.

Cache subscription status

Cache subscription status locally to avoid API calls on every game action. Update the cache when you receive webhook events or when the player opens subscription UI.

Provide clear subscription UI

Show players:

• Their current plan and status
• Next billing date
• Option to cancel or manage payment method
• Clear indication if they're in a trial period