Lumina Print API Documentation

Authenticates a user and returns an access token. Use the returned token in the Authorization header for all other requests.

Body Parameters

Request Example

{
  "username": "clientTest",
  "password": "your-password"
}

Response Example

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Lists catalog products. Each product includes available_stock. Use the returned sku_code when creating orders.

Query Parameters

Response Fields

Response Example

{
  "content": [
    {
      "sku_code": "101085001200134",
      "reference_sku_code": "CLIENT-SKU-BLACK-L",
      "brand": "Gildan",
      "model": "5000",
      "color": "Black",
      "size": "L",
      "available_stock": 42
    }
  ],
  "page": 0,
  "size": 20,
  "total_elements": 1,
  "total_pages": 1
}

Creates a new print-on-demand order.

The response returns order_code. Store this value for future tracking and cancellation.

Request Body

See the full field-by-field schema in Create Order Body.

Response Example

{
  "order_code": "ORD-RBYSTKKRB27Q",
  "reference_id": "client-order-10001",
  "status": "APPROVED",
  "created_at": "2026-05-25T20:15:30Z"
}

Lists orders belonging to the authenticated client.

Query Parameters

Response Example

{
  "content": [
    {
      "order_code": "ORD-RBYSTKKRB27Q",
      "reference_id": "client-order-10001",
      "status": "IN_PRODUCTION",
      "created_at": "2026-05-25T20:15:30Z"
    }
  ],
  "page": 0,
  "size": 20,
  "total_elements": 1,
  "total_pages": 1
}

Returns one order owned by the authenticated client. The path value can be either Lumina's order_code or your own reference_id.

Path Parameters

Response Example

{
  "order_code": "ORD-RBYSTKKRB27Q",
  "reference_id": "client-order-10001",
  "status": "IN_PRODUCTION",
  "recipient": {
    "name": "Jane Customer",
    "city": "Austin",
    "state": "TX",
    "country": "US",
    "zip": "78701"
  },
  "order_items": [
    {
      "sku": "101085001200134",
      "quantity": 1,
      "name": "Black Large Shirt",
      "placements": [
        {
          "placement": "front",
          "technique": "DTG"
        }
      ]
    }
  ],
  "created_at": "2026-05-25T20:15:30Z",
  "updated_at": "2026-05-25T20:20:12Z"
}

Requests cancellation for an eligible order. Lumina Print first asks the production provider to cancel. If the provider does not confirm cancellation, Lumina Print will not cancel the local order.

Path Parameters

Body Parameters

Request Example

{
  "reason": "Customer requested cancellation"
}

Response Fields

Response Example

{
  "order_code": "ORD-RBYSTKKRB27Q",
  "reference_id": "client-order-10001",
  "status": "cancelled",
  "can_cancel": false
}

Creates a webhook subscription for the authenticated client. The secret is returned only once on creation; store it securely.

Body Parameters

Request Example

{
  "endpoint_url": "https://your-system.example.com/lumina/webhooks",
  "event_types": ["order.created", "order.status_updated"]
}

Response Example

{
  "id": "7e56d82d-2112-4f98-b6f8-6e6fa5c4b313",
  "endpoint_url": "https://your-system.example.com/lumina/webhooks",
  "event_types": ["order.created", "order.status_updated"],
  "active": true,
  "secret": "whsec_...",
  "created_at": "2026-05-25T20:15:30Z",
  "updated_at": "2026-05-25T20:15:30Z",
  "message": "Store the secret now — it is only returned on creation and rotate-secret."
}

Lists all webhook subscriptions owned by the authenticated client. The response is a flat JSON array — there is no pagination wrapper. Subscription counts per client are bounded by tenant policy, so the full list is returned in one response.

Response Example

[
  {
    "id": "7e56d82d-2112-4f98-b6f8-6e6fa5c4b313",
    "endpoint_url": "https://your-system.example.com/lumina/webhooks",
    "event_types": ["order.created", "order.status_updated"],
    "active": true,
    "created_at": "2026-05-25T20:15:30Z",
    "updated_at": "2026-05-25T20:15:30Z"
  }
]

Returns one webhook subscription owned by the authenticated client.

Path Parameters

Updates a webhook subscription. Send only fields that should change.

Path Parameters

Body Parameters

Request Example

{
  "active": false
}

Deletes a webhook subscription. Future matching events will no longer be delivered to this endpoint.

Path Parameters

Sends a test webhook to the subscription URL. Test deliveries are for connectivity verification and should not create or update real orders in your system.

Path Parameters

Response Example

{
  "delivered": true,
  "status_code": 200,
  "message": "Test webhook delivered"
}

Lists webhook delivery attempts for the authenticated client. Use this endpoint to debug failed or retried webhook deliveries.

Query Parameters

Response Example

{
  "content": [
    {
      "id": "d63156a3-6a09-4fe6-bbe9-88c427a1e5ed",
      "subscription_id": "7e56d82d-2112-4f98-b6f8-6e6fa5c4b313",
      "event_id": "evt_01HY...",
      "event_type": "order.status_updated",
      "status": "SUCCEEDED",
      "http_status": 200,
      "attempt_count": 1,
      "next_retry_at": null,
      "last_error": null,
      "created_at": "2026-05-25T20:20:00Z",
      "completed_at": "2026-05-25T20:20:01Z"
    }
  ],
  "page": 0,
  "size": 20,
  "total_elements": 1,
  "total_pages": 1
}

Field notes:

• http_status — HTTP response status from your endpoint on the last attempt. null until the first dispatch is attempted.
• next_retry_at — present only while the row is in RETRYING. Cleared on terminal status.
• last_error — last failure detail (connection error, non-2xx body excerpt). Useful for diagnosing your endpoint without enabling delivery payload logging.
• completed_at — set when the row reaches a terminal status (SUCCEEDED, FAILED, EXHAUSTED, CANCELLED).