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.

Quick Start

Get started with the Starship Rewards API in just a few steps:

1. Set Up API Keys - Generate your API Key & Secret from the Client Portal
2. Explore Products - Browse the product catalog
3. Calculate Charges - Get pricing and fees for orders
4. Place Orders - Create orders for vouchers
5. Fetch Vouchers - Retrieve delivered vouchers from orders
6. Set Up Webhooks - Receive real-time order status notifications

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. 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_live_your_api_key_here
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

• Rate Limit: 1000 requests per hour per API key
• Burst Limit: 100 requests per minute
• 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

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.