AstroSell
Get started
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"
}

Update a product

PUT
PUT/v1/products/:id

Updates any subset of a product’s fields — only the keys you send are changed. Pass warehouseId to relink the serials pool, or null to unlink it.

Body parameters
title
string
Product name.
price
number
New price, ≥ 0.
description
string
Storefront description.
visibility
string
public, unlisted or private.
featured
boolean
Pin to the top of the storefront.
category
string
Category id, or null to clear.
warehouseId
string
Relink the serials pool (null unlinks).
curl -X PUT https://api.astrosell.io/api/v1/products/66f0a1... \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "price": 5.49, "featured": true }'
200RESPONSE
{
  "id": "66f0a1...",
  "title": "Netflix Premium 1 Month",
  "price": 5.49,
  "featured": true,
  "visibility": "public"
}

Delete a product

DELETE
DELETE/v1/products/:id

Permanently deletes a product. If it had an auto-created warehouse that no other product uses, that warehouse is removed too; shared warehouses are left intact.

curl -X DELETE https://api.astrosell.io/api/v1/products/66f0a1... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{ "ok": true }

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 categories

GET
GET/v1/categories

Returns your storefront categories (collections), sorted by sortOrder then name.

curl https://api.astrosell.io/api/v1/categories \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
[
  { "_id": "66f0d4...", "name": "Streaming", "sortOrder": 0 }
]

Create a category

POST
POST/v1/categories

Creates a storefront category that buyers can filter products by.

Body parameters
name
string
REQUIREDCategory name.
sortOrder
integer
Lower sorts first (default 0).
curl https://api.astrosell.io/api/v1/categories \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Streaming", "sortOrder": 0 }'
200RESPONSE
{ "_id": "66f0d4...", "name": "Streaming", "sortOrder": 0 }

Update a category

PUT
PUT/v1/categories/:id

Renames or reorders a category.

Body parameters
name
string
New name.
sortOrder
integer
New sort position.
curl -X PUT https://api.astrosell.io/api/v1/categories/66f0d4... \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Streaming services" }'
200RESPONSE
{ "_id": "66f0d4...", "name": "Streaming services", "sortOrder": 0 }

Delete a category

DELETE
DELETE/v1/categories/:id

Deletes a category and unassigns it from every product that used it.

curl -X DELETE https://api.astrosell.io/api/v1/categories/66f0d4... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{ "ok": true }

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"]
}

Get warehouse stock

GET
GET/v1/warehouses/:id/stock

Returns the live serial pool for a warehouse — the available, undelivered keys.

curl https://api.astrosell.io/api/v1/warehouses/66f0c3.../stock \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{
  "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
}

Update a warehouse

PUT
PUT/v1/warehouses/:id

Updates a warehouse’s settings (not the serials themselves — use the stock endpoints for those).

Body parameters
name
string
Internal pool name.
removeDuplicates
boolean
Drop duplicate keys on add.
removeSold
boolean
Remove keys once delivered.
lowStockThreshold
integer
Alert when stock falls to this count (0 = off).
curl -X PUT https://api.astrosell.io/api/v1/warehouses/66f0c3... \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "lowStockThreshold": 25 }'
200RESPONSE
{
  "id": "66f0c3...",
  "name": "Netflix pool",
  "lowStockThreshold": 25
}

Delete a warehouse

DELETE
DELETE/v1/warehouses/:id

Deletes a warehouse. Returns 409 while any product is still linked to it — unlink those products first.

curl -X DELETE https://api.astrosell.io/api/v1/warehouses/66f0c3... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{ "ok": true }

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 customers

GET
GET/v1/customers

Returns your shop’s buyers, newest first, with their store-credit balance and lifetime spend.

Query parameters
limit
integer
Page size, max 500. Defaults to 100.
curl https://api.astrosell.io/api/v1/customers \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
[
  {
    "id": "66f0e5...",
    "email": "buyer@example.com",
    "balance": 12.5,
    "purchaseCount": 7,
    "totalSpent": 64.93,
    "blocked": false
  }
]

Retrieve a customer

GET
GET/v1/customers/:id

Fetches a single customer by id, with their balance, order count and lifetime spend.

curl https://api.astrosell.io/api/v1/customers/66f0e5... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{
  "id": "66f0e5...",
  "email": "buyer@example.com",
  "balance": 12.5,
  "purchaseCount": 7,
  "totalSpent": 64.93
}

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",
    "isFixed": false,
    "value": 10,
    "uses": 42,
    "maxUses": 100,
    "active": true
  }
]

Create a coupon

POST
POST/v1/coupons

Creates a discount code. Use isFixed:true for a flat amount off, or leave it false for a percentage (0–100). maxUses:0 means unlimited.

Body parameters
code
string
REQUIREDThe code buyers enter (upper-cased).
value
number
REQUIREDPercentage (0–100) or fixed amount.
isFixed
boolean
true = flat amount off, false = percent.
maxUses
integer
Total redemptions allowed (0 = unlimited).
active
boolean
Whether the code is usable.
curl https://api.astrosell.io/api/v1/coupons \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "code": "LAUNCH10", "value": 10, "maxUses": 100 }'
200RESPONSE
{
  "code": "LAUNCH10",
  "isFixed": false,
  "value": 10,
  "maxUses": 100,
  "uses": 0,
  "active": true
}

Retrieve a coupon

GET
GET/v1/coupons/:id

Fetches a single coupon by id.

curl https://api.astrosell.io/api/v1/coupons/66f0f6... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{
  "code": "LAUNCH10",
  "isFixed": false,
  "value": 10,
  "maxUses": 100,
  "uses": 42,
  "active": true
}

Update a coupon

PUT
PUT/v1/coupons/:id

Updates a coupon’s discount, limits or active state.

Body parameters
value
number
New discount value.
maxUses
integer
New redemption cap (0 = unlimited).
active
boolean
Enable or disable the code.
curl -X PUT https://api.astrosell.io/api/v1/coupons/66f0f6... \
  -H "Authorization: Bearer nsk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
200RESPONSE
{
  "code": "LAUNCH10",
  "value": 10,
  "active": false
}

Delete a coupon

DELETE
DELETE/v1/coupons/:id

Permanently deletes a coupon code.

curl -X DELETE https://api.astrosell.io/api/v1/coupons/66f0f6... \
  -H "Authorization: Bearer nsk_live_•••"
200RESPONSE
{ "ok": true }

Ready to build?

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