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. Obtain API Credentials - Get your API username and password from the dashboard
2. Authenticate - Exchange credentials for access tokens
3. Explore Products - Browse the product catalog
4. Calculate Charges - Get pricing and fees for orders
5. Check Product Availability - Verify product stock before ordering
6. Place Orders - Create orders for vouchers
7. Fetch Vouchers - Retrieve delivered vouchers from orders

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

Most API endpoints require a Bearer token in the Authorization header:

Authorization: Bearer your_access_token

Public endpoints (no authentication required):

• POST /auth/login - Exchange credentials for tokens
• POST /auth/refresh - Refresh access tokens
• GET /status - Health check endpoint

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

• POST /auth/login - Authenticate with credentials
• POST /auth/refresh - Refresh access token
• POST /auth/logout - Revoke all tokens

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. Token Management: Implement automatic token refresh before expiration
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. Security: Never expose API credentials in client-side code

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.