Starship Rewards API Documentation

Welcome to the Starship Rewards B2B API documentation. This comprehensive guide covers all aspects of integrating with the Starship Rewards platform for gift cards.

Start Here

New to Starship? Read the Getting Started section first — it's five short pages that take you from credentials to a delivered sandbox voucher in under an hour.

Already oriented? Jump straight to the reference:

1. Authentication — API Key + Secret, optional HMAC signing
2. Core Concepts — fulfillment model, order lifecycle, pricing cascade
3. Products — catalog listing and detail
4. Charges — exact pricing quote before ordering
5. Orders — create an order, retrieve vouchers
6. Recharge — real-money mobile top-ups and postpaid bill payments
7. Webhooks — real-time order status callbacks
8. Error Codes — full error envelope and retry guidance

Product Ecosystem

The Starship Rewards API has different parts:

1. Gift Cards

   Digital and physical gift cards from major retailers worldwide. Access thousands of brands across multiple categories with real-time availability and instant delivery options.

2. Mobile Recharge

   Prepaid top-ups and postpaid bill payments on Indian mobile numbers, debited from your pre-funded wallet. Unlike gift cards, a recharge calls the operator immediately and is irreversible once confirmed — see Recharge.

3. Payouts

   Send money directly to beneficiaries via bank transfers, mobile money, and digital wallets. Perfect for disbursements, refunds, rewards, and incentive payments across multiple countries and currencies.

Base URL

All API endpoints are relative to the environment specific hosts:

Production:

{{host}}

Sandbox:

https://api-playground.starshiprewards.com

Authentication

All API endpoints require your API Key and Secret in request headers:

X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke
X-API-Secret: your_api_secret_here

Optionally, enable HMAC request signing for tamper-proof requests. See the full Authentication guide for setup instructions and migration path.

Response Format

Successful Responses

For single resources:

{
  "id": 1,
  "name": "Resource Name",
  "created_at": "2024-01-01T00:00:00Z"
}

For collections, data is returned as an array with pagination in headers:

Response Headers

X-Page: 1
X-Per-Page: 50
X-Total-Count: 195
X-Total-Pages: 4
X-Page-Size: 50
X-Has-More: true

Response Body

[
  {
    "id": 1,
    "name": "Item 1"
  },
  {
    "id": 2,
    "name": "Item 2"
  }
]

Pagination Headers

Query Parameters

For paginated endpoints:

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

Error Response Format

{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "details": {
    "field_name": ["Error message 1", "Error message 2"]
  }
}

Common Status Codes

Rate Limiting

• General: 1,000 requests per hour per API key, shared across every /api/v1/* endpoint
• Order creation: 100 requests per minute per API key (POST /api/v1/orders)
• Full detail, including how rules are matched: Rate Limits
• Rate limit information is included in response headers:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets

Available Endpoints

Authentication

• All /api/v1/* endpoints - Authenticated via X-API-Key + X-API-Secret headers
• Optional X-Signature header for HMAC-signed requests

Reference Data

• GET /api/v1/countries - List all countries
• GET /api/v1/countries/{id} - Get country details
• GET /api/v1/currencies - List all currencies
• GET /api/v1/categories - List all categories
• GET /api/v1/categories/{id} - Get category details
• GET /api/v1/subcategories - List all subcategories
• GET /api/v1/subcategories/{id} - Get subcategory details

Products

• GET /api/v1/products - List all products
• GET /api/v1/products/{id} - Get product details
• POST /api/v1/products/{id}/charges - Calculate charges for a product
• POST /api/v1/products/{id}/discount - Get available discounts

Wallets

• GET /api/v1/wallets - List client wallets
• GET /api/v1/wallets/{id} - Get wallet details

Transactions

• GET /api/v1/transactions - List transactions
• GET /api/v1/transactions/{id} - Get transaction details

Recharge

• GET /api/v1/recharge/operators - List mobile operators
• POST /api/v1/recharge/charges - Preview recharge price (face, discount, payable)
• POST /api/v1/recharges - Place a recharge (requires Idempotency-Key)
• GET /api/v1/recharges - List recharges
• GET /api/v1/recharges/{id} - Get recharge details

Payouts

• GET /api/v1/beneficiaries - List saved beneficiaries
• POST /api/v1/beneficiaries - Create a new beneficiary
• GET /api/v1/beneficiaries/{id} - Get beneficiary details
• DELETE /api/v1/beneficiaries/{id} - Delete a beneficiary
• GET /api/v1/payouts - List payouts
• POST /api/v1/payouts - Create a new payout
• GET /api/v1/payouts/{id} - Get payout details
• POST /api/v1/payouts/{id}/cancel - Cancel a payout

Best Practices

1. Secure Credentials: Store API keys and secrets in environment variables or a secrets manager
2. Error Handling: Always handle rate limiting and network errors gracefully
3. Pagination: Use pagination headers to navigate large result sets efficiently
4. Caching: Cache reference data (countries, currencies) locally when possible
5. Webhooks: Use webhooks instead of polling for order status updates
6. HMAC Signing: Enable HMAC request signing for production integrations

Support

Need help with integration?

• Technical Documentation: Browse our comprehensive API Reference
• Code Examples: Check the examples in each endpoint documentation
• Support Team: Contact technical support for assistance
• Status Page: Monitor API status and incidents

Ready to get started? Begin with Authentication to set up your API access.