Sandbox Setup Guide

The Lumaprints Sandbox is a fully separate environment for building and testing your integration. Orders placed in the Sandbox are never printed, shipped, or billed, so you can safely exercise the full order lifecycle before going live.

Do not submit test orders to Production. Every order submitted to Production enters the real fulfillment workflow: it is queued for printing, reviewed by the production team, and moves through packing and shipping like any customer order. Test orders occupy those queues and staff time and delay real customer orders. Submitting test orders to Production results in permanent revocation of your API access.

The Sandbox is intended only for testing API integrations. Connected store integrations (Shopify, WooCommerce, Squarespace, Order Desk, and other platform connections) are not supported in the Sandbox and will not sync orders. If you need to test a connected store, do so against your Production account.

This guide walks you through everything needed to make your first successful Sandbox request.

Environments

	Sandbox	Production
Dashboard	https://sandbox.lumaprints.com	https://dashboard.lumaprints.com
API base URL	https://us.api-sandbox.lumaprints.com/api/v1	https://us.api.lumaprints.com/api/v1
API keys	Developer > API Keys	Developer > API Keys
Orders fulfilled	No	Yes
Cards charged	No (test cards only)	Yes

Sandbox and Production are completely isolated. Accounts, stores, API keys, orders, and payment methods do not carry over between them.

Step 1: Create a Sandbox account

Go to https://sandbox.lumaprints.com and register a new account.

You may reuse the same email address as your Production account, but the Sandbox account is separate and requires its own registration.

Step 2: Create a Standard Store

API order creation is only supported for Standard Stores. Stores connected through a platform integration (Shopify, WooCommerce, Squarespace, Order Desk, and others) sync orders automatically and cannot accept orders through the API.

In the Sandbox dashboard, open the Stores section.

Create a new store and select the Standard Store type.

Note the store name. You will retrieve its storeId through the API in Step 5.

If you plan to run multiple integrations or environments, create a separate Standard Store for each one so orders stay clearly separated.

Step 3: Add a payment method and billing address

Every store must have a primary payment method and a default billing address before the API will accept orders. Order submissions will be rejected until both are set.

In the Sandbox dashboard, open your account's payment settings.

Add a payment method using one of the test cards below and mark it as the primary card.

Set a default billing address for the store.

Sandbox test cards

Any of the following card numbers are accepted in the Sandbox. Use any future expiration date in MM/YY format and any 3-digit (4-digit for Amex) CVV.

Card type	Number
Visa	4111111111111111
Mastercard	5555555555554444
American Express	378282246310005
Discover	6011000991300009
JCB	3530111333300000

The full list of accepted test numbers is on the Payment Method and Billing Address page. Test cards are never charged and are rejected in Production.

Step 4: Generate API credentials

In the Sandbox dashboard, go to Developer > API Keys (https://sandbox.lumaprints.com/developer/apiKeys).

Generate a new key pair. You will receive an API Key and an API Secret.

Store the secret securely. Treat Sandbox credentials with the same care as Production credentials, and never commit them to source control.

Step 5: Make your first request

The API uses HTTP Basic authentication. The API Key is the username and the API Secret is the password.

Build the Authorization header by Base64-encoding the string apiKey:apiSecret and prefixing it with Basic .

Verify your setup by listing the stores available for API order creation:

A successful response returns your Standard Store(s):

[
  {
    "storeId": 1088,
    "storeName": "My Test Store"
  }
]

Use the returned storeId in all subsequent order and webhook requests. If the response is an empty array, confirm that the store you created in Step 2 is a Standard Store.

Step 6: Submit a test order

With a storeId in hand, you can walk the standard order flow:

Browse the catalog. Call GET /products/categories, then GET /products/{categoryId}/subcategories and the subcategory options endpoint to find the product configuration you want to order.

Validate your artwork. Call POST /images/check with the image URL to confirm resolution and format are acceptable for the selected product before placing the order.

Estimate shipping. Call POST /shipping/cost to preview shipping charges for the recipient address.

Submit the order. Call POST /orders with your externalId, storeId, shipping method, production time, recipient, and order items.

Retrieve the order. Call GET /orders/{orderNumber} to confirm the order was created with the expected data. Sandbox orders stay in their initial status, so GET /shipments/{orderNumber} will not return shipment data; exercise that endpoint against a Production order once live.

Image URLs in your order payload must be publicly accessible. The Sandbox fetches artwork the same way Production does, so URLs behind authentication or on a local network will fail validation.

Step 7: Test webhooks

Subscribe to order events so your system is notified without polling. Register an endpoint with POST /webhook, providing the event name, your storeId, the destination URL, and the Basic auth username and password Lumaprints should use when calling it.

For local development, use a tunneling tool such as ngrok or Cloudflare Tunnel to expose your endpoint over HTTPS. Note that because Sandbox orders do not progress through statuses, order lifecycle events such as shipping will not be triggered. Use the Sandbox to confirm your subscription is registered correctly and your endpoint accepts the configured Basic auth; end-to-end webhook delivery should be verified in Production.

Sandbox behavior and limitations

The Sandbox supports API integrations only. Connected store integrations do not function in the Sandbox.

Sandbox orders do not progress through statuses. An order remains in its initial status after submission and is never moved to production, shipped, or marked complete.

Because orders do not progress, GET /shipments/{orderNumber} will not return shipment data and shipping webhook events will not fire in the Sandbox. Use the Sandbox to validate authentication, catalog lookups, image checks, pricing, and order submission payloads.

Rate limits are the same as Production. See the API Rate Limits page for details.

Catalog data (categories, subcategories, options, pricing) mirrors Production but may lag behind on recently launched products.

Sandbox data may be reset periodically. Do not rely on Sandbox orders persisting long term.

Moving to Production

Only switch to Production once your integration has been fully validated in the Sandbox. Production has no test mode: any order you submit there is a real order that will be printed, charged, and shipped, and it cannot be flagged as a test after the fact. Submitting test orders to Production results in permanent revocation of your API access.

When your integration is ready:

Create a Standard Store in Production and add a real payment method and billing address.

Generate Production API credentials under Developer > API Keys.

Update your base URL to https://us.api.lumaprints.com/api/v1 and swap in the Production credentials.

Re-run the store listing request to confirm the new storeId, then update any stored references.

Store IDs, order numbers, and webhook subscriptions are environment-specific and must be recreated in Production.

Troubleshooting

Symptom	Likely cause
`401 Unauthorized`	Authorization header is malformed, or the credentials are from the wrong environment.
`GET /stores` returns `[]`	No Standard Store exists on the account. Platform-connected stores are not listed.
Order rejected for missing payment method	Primary payment method or default billing address has not been set for the store.
Image check fails	Image URL is not publicly reachable, or the file does not meet the product's resolution requirements.
Webhook never fires	Expected in the Sandbox, since orders do not progress and lifecycle events are not emitted. In Production, check that the endpoint is reachable over HTTPS and the subscription uses the correct `storeId`.

Support

The API is currently in open beta. If you encounter issues or have suggestions, contact the Lumaprints API team by email through the address listed on the Introduction page.

Environments#

Step 1: Create a Sandbox account#

Step 2: Create a Standard Store#

Step 3: Add a payment method and billing address#

Step 4: Generate API credentials#

Step 5: Make your first request#

Step 6: Submit a test order#

Step 7: Test webhooks#

Sandbox behavior and limitations#

Moving to Production#

Troubleshooting#

Support#