API REFERENCE · v1

AstroSell Commerce API

Sell digital goods programmatically. List and create products, manage shared serial warehouses, restock instantly, and read your orders and coupons — over a predictable, key-authenticated REST API.

https://api.astrosell.io/api/v1 Bearer key auth · TLSJSON over HTTPS

Introduction

The AstroSell API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP verbs and status codes.

All requests go to https://api.astrosell.io/api/v1 and must be sent over HTTPS. Authenticate with a secret API key you generate in your dashboard under Settings → API — every key is scoped to your shop.

# List your products
curl https://api.astrosell.io/api/v1/products \
  -H "Authorization: Bearer nsk_live_•••"

Authentication

Authenticate every request with your secret key in the Authorization header as a Bearer token (the X-API-Key header works too). Keys carry full access to your shop — keep them secret and never ship them in client-side code or commit them to version control.

Generate and revoke keys anytime from your dashboard under Settings → API. A revoked key stops working immediately. Keys are shown only once at creation, and start with nsk_.

Headers

Authorization

header

REQUIREDBearer nsk_… — your secret API key.

X-API-Key

header

Alternative to the Authorization header — pass the raw nsk_ key.

curl https://api.astrosell.io/api/v1/products \
  -H "Authorization: Bearer nsk_live_•••"

# …or with the X-API-Key header
curl https://api.astrosell.io/api/v1/products \
  -H "X-API-Key: nsk_live_•••"

Errors & rate limits

AstroSell uses conventional HTTP status codes. 2xx means success, 4xx indicates a problem with your request (a missing field, an invalid or revoked key, a resource that doesn’t exist), and 5xx signals an error on our side. Every error returns a JSON body with a human-readable message.

The API is rate limited per key. If you exceed the limit you’ll receive a 429 — back off briefly and retry.

# 401 — bad or revoked key
{
  "error": "Invalid or revoked API key"
}

# 404 — not found
{
  "error": "Product not found"
}

List products

GET

GET/v1/products

Returns every product in your shop, newest first. For serials-type products, stock is the live count of available items in the linked warehouse; service, file and dynamic products are unlimited.

curl https://api.astrosell.io/api/v1/products \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

[
  {
    "id": "66f0a1...",
    "title": "Netflix Premium 1 Month",
    "slug": "netflix-premium-1-month",
    "price": 4.99,
    "currency": "USD",
    "type": "serials",
    "stock": 142,
    "unlimitedStock": false,
    "visibility": "public",
    "salesCount": 318,
    "createdAt": "2026-06-01T12:00:00.000Z"
  }
]

Retrieve a product

GET

GET/v1/products/:id

Fetches a single product by its id, including its stock items — the actual serials drawn from the product’s warehouse (or its inline stock for legacy products).

curl https://api.astrosell.io/api/v1/products/66f0a1... \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

{
  "id": "66f0a1...",
  "title": "Netflix Premium 1 Month",
  "price": 4.99,
  "currency": "USD",
  "type": "serials",
  "stock": 142,
  "stockItems": [
    "NFLX-AAAA-BBBB",
    "NFLX-CCCC-DDDD"
  ]
}

Create a product

POST

POST/v1/products

Creates a product in your shop. For serials, pass "stock" (newline-separated keys) to auto-create a dedicated warehouse, or "warehouseId" to draw from an existing shared pool. Other types (service, file, dynamic) are unlimited and need no stock.

Body parameters

title

string

REQUIREDProduct name shown to buyers.

price

number

REQUIREDPrice in the product currency, ≥ 0.

type

string

serials (default), service, file or dynamic.

stock

string

Newline-separated serials — auto-creates a warehouse for this product.

warehouseId

string

Link an existing warehouse instead of creating one.

currency

string

USD (default), EUR, GBP, CAD.

purchaseNote

string

Shown to the buyer after purchase.

visibility

string

public (default), unlisted or private.

curl https://api.astrosell.io/api/v1/products \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Steam Gift Card $20",
    "price": 18.5,
    "type": "serials",
    "stock": "CODE-1\nCODE-2\nCODE-3",
    "purchaseNote": "Thanks for your order!"
  }'

200RESPONSE

{
  "id": "66f0b2...",
  "title": "Steam Gift Card $20",
  "price": 18.5,
  "currency": "USD",
  "type": "serials",
  "stock": 3,
  "visibility": "public"
}

Add product stock

POST

POST/v1/products/:id/stock

Appends serials to a serials-type product. If the product is backed by a warehouse the keys are added there (restocking every linked product); otherwise they’re added to the product’s own pool. Duplicates can be removed automatically.

Body parameters

stock

string

REQUIREDNewline-separated serials to append.

removeDuplicates

boolean

Drop keys already present (and within this batch).

curl https://api.astrosell.io/api/v1/products/66f0a1.../stock \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "stock": "NEW-1\nNEW-2", "removeDuplicates": true }'

200RESPONSE

{
  "added": 2,
  "total": 144,
  "truncated": false,
  "capped": false
}

List warehouses

GET

GET/v1/warehouses

Lists your warehouses — shared serial pools that one or more products can draw stock from. Newest first.

curl https://api.astrosell.io/api/v1/warehouses \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

[
  {
    "id": "66f0c3...",
    "name": "Netflix pool",
    "count": 142,
    "removeDuplicates": true,
    "lowStockThreshold": 20
  }
]

Create a warehouse

POST

POST/v1/warehouses

Creates a shared serial pool you can attach to products. Seed it with stock immediately and configure dedup, sold-key removal and a low-stock threshold.

Body parameters

name

string

REQUIREDA label for the pool.

stock

string

Newline-separated serials to seed it with.

removeDuplicates

boolean

Drop duplicate keys (default true).

removeSold

boolean

Remove keys once delivered (default true).

lowStockThreshold

integer

Notify when stock falls to this count.

curl https://api.astrosell.io/api/v1/warehouses \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Netflix pool", "stock": "A\nB\nC" }'

200RESPONSE

{
  "id": "66f0c3...",
  "name": "Netflix pool",
  "count": 3,
  "removeDuplicates": true,
  "removeSold": true
}

Retrieve a warehouse

GET

GET/v1/warehouses/:id

Fetches a single warehouse by id, including its current stock items and settings.

curl https://api.astrosell.io/api/v1/warehouses/66f0c3... \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

{
  "id": "66f0c3...",
  "name": "Netflix pool",
  "count": 142,
  "items": ["NFLX-AAAA-BBBB", "NFLX-CCCC-DDDD"]
}

Add warehouse stock

POST

POST/v1/warehouses/:id/stock

Appends serials to a warehouse. Every product linked to the pool is restocked automatically.

Body parameters

stock

string

REQUIREDNewline-separated serials to append.

removeDuplicates

boolean

Defaults to the warehouse setting.

curl https://api.astrosell.io/api/v1/warehouses/66f0c3.../stock \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "stock": "NEW-1\nNEW-2" }'

200RESPONSE

{
  "added": 2,
  "total": 144,
  "truncated": false,
  "capped": false
}

List orders

GET

GET/v1/orders

Returns your shop’s orders, newest first. Filter by status and cap the page size with limit.

Query parameters

status

string

e.g. completed, pending, processing, expired, refunded.

limit

integer

Page size, 1–200. Defaults to 50.

curl -G https://api.astrosell.io/api/v1/orders \
  -H "Authorization: Bearer nsk_live_•••" \
  -d status=completed -d limit=2

200RESPONSE

[
  {
    "invoiceId": "AS-7KD2P9",
    "productTitle": "Netflix Premium 1 Month",
    "total": 4.99,
    "currency": "USD",
    "status": "completed",
    "gateway": "crypto",
    "createdAt": "2026-06-20T10:11:12.000Z",
    "deliveredItems": ["NFLX-AAAA-BBBB"]
  }
]

Retrieve an order

GET

GET/v1/orders/:invoiceId

Fetches a single order by its invoice id, including its status and — once completed — the delivered items.

curl https://api.astrosell.io/api/v1/orders/AS-7KD2P9 \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

{
  "invoiceId": "AS-7KD2P9",
  "productTitle": "Netflix Premium 1 Month",
  "total": 4.99,
  "currency": "USD",
  "status": "completed",
  "customerEmail": "buyer@example.com",
  "deliveredItems": ["NFLX-AAAA-BBBB"]
}

List coupons

GET

GET/v1/coupons

Returns every coupon in your shop with its discount, limits and usage.

curl https://api.astrosell.io/api/v1/coupons \
  -H "Authorization: Bearer nsk_live_•••"

200RESPONSE

[
  {
    "code": "LAUNCH10",
    "type": "percent",
    "value": 10,
    "uses": 42,
    "maxUses": 100,
    "expiresAt": "2026-12-31T00:00:00.000Z"
  }
]

Ready to build?

Generate a key in your dashboard and make your first call in under a minute.

Open dashboard Create API key