List, search, and retrieve detailed product information from the Starship Rewards catalog

Products API

The Products API provides access to the Starship Rewards product catalog with comprehensive search, filtering, and detailed product information retrieval capabilities.

Overview

The Products API consists of three main endpoints:

List Products - Search and filter the product catalog with pagination
Get Product Details - Retrieve comprehensive information for a specific product
Check Availability - Verify if a product is available for purchase at specific quantity/denomination

All product endpoints require authentication and return data in a consistent JSON format.

List Products

Get a paginated list of products with advanced search and filtering options.

Endpoint

GET /api/v1/products

Authentication: API Key + Secret required

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (min: 1)
`limit`	number	50	Items per page (min: 1, max: 10,000)
`category`	string	-	Filter by category name (e.g., "Gift Cards")
`sort`	object	`{"field":"id","direction":"DESC"}`	Sort configuration

Sort Object Format

{
  "field": "id",
  "direction": "ASC" // or "DESC"
}

Response

Success Response (200 OK)

Headers:

X-Page: 1
X-Per-Page: 50
X-Total-Count: 1247
X-Total-Pages: 25
X-Page-Size: 50
X-Has-More: true

Response Body:

[
  {
    "id": 1001,
    "name": "Amazon Gift Card - USD",
    "category": "Gift Cards",
    "sub_category": "E-commerce",
    "country_id": 1,
    "currency_id": 1,
    "image_url": "https://cdn.starship.com/products/amazon-gc.jpg",
    "delivery_type": "code",
    "delivery_time": "instant",
    "validity": "No expiry",
    "available_denominations": [
      {
        "min_value": 10.00,
        "max_value": 500.00,
        "discount": 2.5
      }
    ]
  },
  {
    "id": 2001,
    "name": "Google Play Gift Card - USD", 
    "category": "Gift Cards",
    "sub_category": "Digital Entertainment",
    "country_id": 1,
    "currency_id": 1,
    "image_url": "https://cdn.starship.com/products/google-play.jpg",
    "delivery_type": "code_with_pin",
    "delivery_time": "delayed",
    "validity": "No expiry",
    "available_denominations": [
      {
        "min_value": 5.00,
        "max_value": 100.00,
        "discount": 1.8
      }
    ]
  }
]

Product Object Fields

Field	Type	Description
`id`	number	Unique product identifier
`name`	string	Product display name
`category`	string	Primary category (e.g., "Gift Cards", "Mobile Top-up")
`sub_category`	string	Subcategory classification
`country_id`	number	Supported country ID
`currency_id`	number	Product currency ID
`image_url`	string	Product image URL
`delivery_type`	string	How the voucher is delivered. See Delivery Type Values below
`delivery_time`	string	Estimated fulfillment speed. See Delivery Time Values below
`validity`	string	Product validity period
`terms`	string	Terms and conditions (optional)
`details`	string	Product description (optional)
`how_to_use`	string	Usage instructions (optional)
`available_denominations`	array	Available purchase amounts with discounts

Delivery Type Values

All products on Starship are digital vouchers. The delivery_type indicates the format of the voucher delivered in the order response.

Value	Description	Order Response Fields
`code`	A single voucher/redemption code	`pin` contains the code
`code_with_pin`	A voucher code plus a separate PIN (e.g., some mobile top-ups, gaming cards)	`pin` contains the code, `pin_code` contains the separate PIN

Delivery Time Values

The delivery_time field is dynamic — it reflects real-time inventory availability at the moment of the API call, not a static product attribute.

Value	Meaning	What to Expect
`instant`	Inventory is available in cache for the requested product/denomination	Order will be fulfilled immediately upon placement
`delayed`	No pre-stocked inventory currently available	Order will be queued as `PENDING` and fulfilled when inventory is sourced (typically within minutes to hours)

Note: A product may show instant for one denomination and delayed for another, depending on current stock levels. The delivery_time on the product listing reflects general availability — use the Check Availability endpoint for denomination-specific checks before placing orders.

Examples

# Get all products (default pagination)
curl -X GET "{{host}}/api/v1/products" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Filter by category with custom pagination
curl -X GET "{{host}}/api/v1/products?category=Gift%20Cards&page=1&limit=20" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Sort by name in ascending order
curl -X GET "{{host}}/api/v1/products?sort=%7B%22field%22%3A%22name%22%2C%22direction%22%3A%22ASC%22%7D" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Get Product Details

Retrieve comprehensive information for a specific product, including detailed product information.

Endpoint

GET /api/v1/products/{id}

Authentication: API Key + Secret required

Path Parameters

Parameter	Type	Required	Description
`id`	number	Yes	Product ID (must be > 0)

Query Parameters

Parameter	Type	Default	Description

Response

Success Response (200 OK)

{
  "id": 1001,
  "name": "Amazon Gift Card - USD",
  "category": "Gift Cards",
  "sub_category": "E-commerce",
  "country_id": 1,
  "currency_id": 1,
  "image_url": "https://cdn.starship.com/products/amazon-gc.jpg",
  "delivery_type": "code",
  "delivery_time": "instant",
  "validity": "No expiry",
  "terms": "Redeemable on Amazon.com. Cannot be resold or transferred for cash. Gift card will not be replaced if lost, stolen, or used without permission.",
  "details": "Digital gift card for Amazon.com purchases. Valid for millions of items across all categories. Perfect for personal use or as a gift.",
  "how_to_use": "1. Add items to your Amazon cart\n2. Proceed to checkout\n3. Enter gift card code in the payment section\n4. Complete your purchase",
  "available_denominations": [
    {
      "min_value": 10.00,
      "max_value": 500.00,
      "discount": 2.5
    }
  ]
}

Examples

# Get basic product details
curl -X GET "{{host}}/api/v1/products/1001" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get product with full details
curl -X GET "{{host}}/api/v1/products/1001" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Check Product Availability

Check if a product is available for purchase at a specific denomination and quantity without calculating full charges.

Endpoint

POST /api/v1/products/{id}/availability

Authentication: API Key + Secret required

Path Parameters

Parameter	Type	Required	Description
`id`	number	Yes	Product ID (must be > 0)

Request Body

{
  "denomination": 100.00,
  "quantity": 2
}

Field	Type	Required	Validation	Description
`denomination`	number	Yes	Min: 0.01, Max: 1,000,000,000	Purchase amount per unit
`quantity`	number	Yes	Min: 1	Number of units to check

Response

Success Response (200 OK)

{
  "is_available": true
}

Response Fields

Field	Type	Description
`is_available`	boolean	Whether the product is available for the requested denomination and quantity

Use Cases

Pre-purchase Validation - Check availability before showing pricing options
Real-time Inventory - Display current stock status to users
Performance Optimization - Lighter check than full charge calculation
User Experience - Show availability indicators in product listings

Examples

# Check if product is available
curl -X POST "{{host}}/api/v1/products/1001/availability" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 100.00,
    "quantity": 2
  }'

# Check large quantity availability
curl -X POST "{{host}}/api/v1/products/1001/availability" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "quantity": 100
  }'

Error Handling

Common Error Responses

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid product ID"
}

404 Not Found

{
  "error": "not_found",
  "message": "Product not found"
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired access token"
}

Error Handling Best Practices

Always validate product IDs before making requests
Handle 404 responses gracefully as products may become unavailable
Implement retry logic with exponential backoff for 5xx errors
Cache product data to reduce API calls and improve performance
Check pagination headers when processing large datasets

Rate Limits

Product Listing: 100 requests per minute
Product Details: 200 requests per minute
Burst Limit: 20 requests per 10 seconds

Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets

Next Steps

Learn how to Calculate Charges for selected products
Explore Categories for product organization
Check Countries for regional availability

Products API

On this page