@sellersmith/shineon-sdk

TypeScript SDK for the ShineOn fulfillment API. Zero runtime dependencies, CJS/ESM dual build, Node 18+.

Install

npm install @sellersmith/shineon-sdk

Quick Start

import { ShineOn } from '@sellersmith/shineon-sdk';

const client = new ShineOn({ token: process.env.SHINEON_API_TOKEN! });

// Create an order (V1)
const { order } = await client.orders.create({
  order: {
    source_id: 'store-order-1001',
    shipment_notification_url: 'https://yourstore.com/webhooks/shineon',
    shipping_method: 'standard-us',
    shipping_address: {
      name: 'Jane Smith',
      address1: '123 Main St',
      city: 'Austin',
      zip: '78701',
      country_code: 'US',
    },
    line_items: [
      {
        store_line_item_id: 'item-1',
        sku: 'SNO-NECKLACE-GOLD',
        quantity: 1,
        properties: { 'Engraving Line 1': 'Always & Forever' },
      },
    ],
  },
});

console.log(order.id, order.status); // 98765 'awaiting_payment'

Configuration

const client = new ShineOn({
  token: 'your-api-token',     // required
  baseUrl: 'https://api.shineon.com', // optional, default shown
  timeout: 30_000,             // optional, ms (default 30 000)
  maxRetries: 3,               // optional, 429 retry attempts (default 3)
});

Option	Type	Default	Description
token	string	—	API access token (required)
baseUrl	string	https://api.shineon.com	Base URL override
timeout	number	30000	Request timeout in milliseconds
maxRetries	number	3	Max retry attempts for rate-limited (429) requests

API Reference

Orders

client.orders.create(params)        // POST /v1/orders
client.orders.createV2(params)      // POST /v2/orders
client.orders.list(params?)         // GET  /v1/orders
client.orders.get(id)               // GET  /v1/orders/{id}
client.orders.update(id, params)    // PUT  /v1/orders/{id}
client.orders.hold(id)              // POST /v1/orders/{id}/hold
client.orders.ready(id)             // POST /v1/orders/{id}/ready
client.orders.cancel(id)            // POST /v1/orders/{id}/cancel

Method	Params	Returns
create(params)	CreateOrderV1Params	Promise<OrderResponse>
createV2(params)	CreateOrderV2Params	Promise<OrderResponse>
list(params?)	ListOrdersParams (optional)	Promise<OrderListResponse>
get(id)	number | string	Promise<OrderResponse>
update(id, params)	number | string, UpdateOrderParams	Promise<OrderResponse>
hold(id)	number | string	Promise<OrderResponse>
ready(id)	number | string	Promise<OrderResponse>
cancel(id)	number | string	Promise<void> (202 Accepted)

ListOrdersParams — all fields optional:

Field	Type	Description
ids	string	Comma-separated order IDs
source_ids	string	Comma-separated source IDs
source_po_numbers	string	Comma-separated source PO numbers
status	OrderStatus	Filter by status
created_at_min	string	ISO 8601 datetime
created_at_max	string	ISO 8601 datetime
updated_at_min	string	ISO 8601 datetime
updated_at_max	string	ISO 8601 datetime
page	number	Page number
limit	number	Max 250, default 50

SKUs

client.skus.list()        // GET /v1/skus
client.skus.get(skuId)    // GET /v1/skus/{skuId}

Method	Params	Returns
list()	—	Promise<SkuListResponse>
get(skuId)	string	Promise<SkuResponse>

SKU properties by type:

SKU type	buyer_uploads	engravings	size_option	Notes
artwork	>0	—	—	Requires print_url in order properties
engraving	—	1 or 2	—	Requires engraving line properties
ring	—	optional	true	Requires Size (US) property
standard	—	—	—	No customization required

Product Templates

client.productTemplates.list(params?)    // GET /v1/product_templates
client.productTemplates.listV2(params?)  // GET /v2/product_templates
client.productTemplates.get(id)          // GET /v1/product_templates/{id}

Method	Params	Returns
list(params?)	ListProductTemplatesV1Params (optional)	Promise<ProductTemplateListResponse>
listV2(params?)	ListProductTemplatesV2Params (optional)	Promise<ProductTemplateListResponse>
get(id)	number | string	Promise<ProductTemplateResponse>

ListProductTemplatesV1Params: page?, per_page? (default 15)

ListProductTemplatesV2Params: page?, per_page?, search? (adds full-text search)

Both list methods return ProductTemplateListResponse — a paginated response with data, links, and meta fields.

Renders

client.renders.get(id)            // GET  /v1/renders/{id}
client.renders.make(id, params)   // POST /v1/renders/{id}/make

Method	Params	Returns
get(id)	number | string	Promise<RenderResponse>
make(id, params)	number | string, MakeRenderParams	Promise<RenderResponse>

MakeRenderParams — provide exactly one image source:

Field	Type	Description
src	string	Source image URL (mutually exclusive with attachment/random)
attachment	string	Base64-encoded source image (mutually exclusive with src/random)
random	number	Set to 1 to use a random sample image
output_width	number	Output width in pixels
output_format	string	Output format: 'png', 'jpg'
output_quality	number	Quality 1–100 (for lossy formats)

V1 vs V2

The key difference is how personalizations are represented on order line items.

V1 uses a flat properties object with named keys:

line_items: [{
  store_line_item_id: 'item-1',
  sku: 'SNO-NECKLACE-GOLD',
  quantity: 1,
  properties: {
    'Engraving Line 1': 'Always & Forever',
    engraving_font: 'Script',   // slug alias also accepted
  },
}]

V2 uses a personalizations array of key/value pairs:

line_items: [{
  store_line_item_id: 'item-1',
  sku: 'SNO-NECKLACE-GOLD',
  quantity: 1,
  personalizations: [
    { key: 'engraving_line_1', value: 'Always & Forever' },
    { key: 'engraving_font',   value: 'Script' },
  ],
}]

V2 product templates (listV2) include a personalizations array that describes each accepted key, its type (text, image_url, svg_url, choice), and validations — use this to discover valid keys before creating an order.

Order Status Flow

on_hold  ──ready()──>  awaiting_payment  ──(auto)──>  in_production  ──(auto)──>  shipped
   ^                          |
   └───────hold()─────────────┘

Any non-shipped status  ──cancel()──>  cancelled

Status	Description
on_hold	Order created with ready: 0 or put on hold manually
awaiting_payment	Order accepted and waiting for production slot
in_production	Order is being manufactured
shipped	Order has shipped; tracking info available on line items
cancelled	Order cancelled; cancel() returns 202 Accepted

update() is only permitted when status is on_hold or awaiting_payment.

Shipping Methods

Value	Description
standard-us	Standard US domestic shipping
international	International shipping
(custom)	Additional methods available in your partner account

The type is 'standard-us' \| 'international' \| string — any string accepted by your ShineOn partner account is valid.

Error Handling

All API errors throw a ShineOnError:

import { ShineOn, ShineOnError } from '@sellersmith/shineon-sdk';

try {
  const { order } = await client.orders.get(99999);
} catch (err) {
  if (err instanceof ShineOnError) {
    console.error(err.message);      // e.g. "Order not found"
    console.error(err.status);       // HTTP status: 404
    console.error(err.responseBody); // raw parsed response body
  }
}

status	Cause
400	Validation error — check responseBody.error for details
401	Invalid or missing API token
404	Resource not found
422	Unprocessable entity
429	Rate limit hit — SDK auto-retries up to maxRetries times
408	Request timed out (client-side)
0	Network error or unknown failure

Rate Limiting

When the API returns 429 Too Many Requests, the SDK automatically retries with exponential backoff:

• Delay uses the Retry-After response header if present
• Otherwise: min(1000 * 2^attempt, 30_000) ms
• Retries up to maxRetries times (default 3)
• After exhausting retries, throws ShineOnError with status: 429

Webhook Integration

Set shipment_notification_url on each order. ShineOn will POST a ShipmentNotification payload to that URL whenever fulfillment status changes.

import type { ShipmentNotification } from '@sellersmith/shineon-sdk';

// Express route handler
app.post('/webhooks/shineon', (req, res) => {
  const payload = req.body as ShipmentNotification;

  for (const item of payload.order.line_items) {
    console.log(
      `Item ${item.store_line_item_id} shipped via ${item.tracking_company}: ${item.tracking_number}`
    );
  }

  res.sendStatus(200);
});

ShipmentNotification shape:

{
  order: {
    id: number;
    source_id: string;
    store_order_id: string;
    line_items: Array<{
      id: number;
      store_line_item_id: string;
      sku: string;
      quantity: number;
      tracking_company: string;
      tracking_number: string;
    }>;
  };
}

TypeScript Support

All types are exported from the package root:

import type {
  ShineOnConfig,
  CreateOrderV1Params,
  CreateOrderV2Params,
  UpdateOrderParams,
  ListOrdersParams,
  OrderResponse,
  OrderListResponse,
  Order,
  OrderStatus,
  ShippingMethod,
  ShippingAddress,
  LineItemProperties,
  Personalization,
  SkuResponse,
  SkuListResponse,
  Sku,
  ProductTemplateResponse,
  ProductTemplateListResponse,
  ProductTemplate,
  TemplatePersonalization,
  RenderResponse,
  MakeRenderParams,
  Render,
  ShipmentNotification,
} from '@sellersmith/shineon-sdk';

License

MIT — see LICENSE.