Deals & Special Pricing

Deals allow you to offer special pricing on purchase items to specific users. Create deals in the devportal and include deal codes in checkout URLs to apply discounted pricing during the purchase flow.

Overview

Deals are pre-configured price overrides tied to specific items. Each deal:

  • Is associated with a single purchase item
  • Has a unique code within that item
  • Applies to either USD or a specific virtual currency (not both)
  • Can be active or inactive
  • Is validated server-side at checkout time

Use Cases

  • Promotional campaigns: Time-limited discounts for marketing events
  • User-specific offers: VIP or loyalty pricing for specific players
  • Influencer partnerships: Special pricing for streamer audiences
  • Retention offers: Win-back pricing for churned users
  • Bundle pricing: Discounted rates when purchased with other items

Creating Deals

Deals are created and managed in the devportal under your game's store items. Navigate to Dashboard → Games → Store Items → [Item] → Deals to create and manage deals for each item.

When creating a deal, you specify:

  • Deal Code: A unique identifier (e.g., SUMMER2024, VIP_10OFF)
  • Currency Type: Either USD or a specific virtual currency
  • Override Price: The new price (in cents for USD, or units for virtual currency)
  • Status: Active or inactive
  • Metadata: Optional key-value pairs for tracking (e.g., campaign name)

Applying Deals

Your game server includes the deal code when initiating checkout. The deal is validated server-side and the discounted price is applied automatically.

Credit Card Checkout (Redirect)

Include the dealCode query parameter when calling the checkout redirect endpoint:

// Server-side: Generate checkout URL with deal code
const response = await fetch(
  'https://api.oncade.gg/v1/checkout/redirect?' + new URLSearchParams({
    gameId: 'your-game-id',
    itemId: '65fa1234abcdef5678901234',
    dealCode: 'SUMMER2024',
    redirectUrl: 'https://yourgame.com/thanks'
  }),
  {
    headers: {
      'x-server-api-key': process.env.ONCADE_SERVER_API_KEY!
    }
  }
);

const { url } = await response.json();
// Redirect player to: url

Wallet Purchase

Include the dealCode in the request body for wallet purchases:

// Server-side: Initiate wallet purchase with deal
const response = await fetch('https://api.oncade.gg/v1/wallet/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-server-api-key': process.env.ONCADE_SERVER_API_KEY!,
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    userId: 'link_usr_abc123',
    itemId: '65fa1234abcdef5678901234',
    dealCode: 'VIP_DISCOUNT'
  })
});

const { data } = await response.json();
// data.purchaseId, data.distributions (with deal pricing applied)

Virtual Currency Purchase

For virtual currency purchases, the deal must be configured for the specific currency being used. Include the dealCode in the request body:

// Server-side: Initiate virtual currency purchase with deal
const response = await fetch('https://api.oncade.gg/v1/vc/purchases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-server-api-key': process.env.ONCADE_SERVER_API_KEY!,
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    userId: 'link_usr_abc123',
    itemId: '65fa1234abcdef5678901234',
    currencyId: 'cur_gems123',
    dealCode: 'GEMS_SALE'
  })
});

const { data } = await response.json();
// data.amountUnits reflects the deal price

Deal Validation

Deals are validated at checkout time. The API will return an error if:

  • The deal code doesn't exist for the item
  • The deal is inactive
  • For virtual currency deals: the deal currency doesn't match the payment currency

If validation fails at the checkout redirect stage, a 400 error is returned. If validation fails during checkout session creation, the purchase proceeds at the regular price (graceful degradation).

Webhook Integration

When a purchase uses a deal, the dealCode is included in the webhook payload. This allows you to track which deals are being used and attribute purchases to specific campaigns.

{
  "event": "Purchases.Completed",
  "data": {
    "purchaseId": "purchase_abc123def456",
    "itemId": "item_abc123def456",
    "gameId": "game_123",
    "itemType": "purchase",
    "amount": 799,
    "currency": "USD",
    "paymentProvider": "card",
    "dealCode": "SUMMER2024",
    "metadata": { "campaign": "summer-promo" },
    "user_ref": "9f2e8d29-2e1b-4db3-aa3f-fd878d4ebb3f"
  },
  "timestamp": "2024-07-14T12:34:56.000Z"
}

API Reference

The following endpoints support deal codes:

Best Practices

  • Use descriptive codes: Choose codes that are easy to remember and identify the campaign (e.g., SUMMER2024 vs ABC123)
  • Track with metadata: Add campaign identifiers in the deal metadata for analytics
  • Deactivate, don't delete: Set deals to inactive rather than deleting them to preserve purchase history references
  • Validate server-side: Always pass deal codes from your server, never trust client-provided codes without validation
  • Monitor usage: Use deal statistics in the devportal to track how often each deal is used

Security Considerations

  • Deal codes are validated server-side; clients cannot manipulate pricing
  • Only your server (with the API key) can initiate purchases with deal codes
  • The deal price is locked when the purchase is created, not when completed
  • Invalid or inactive deal codes result in API errors, not silent failures