FAQ

This FAQ answers common questions about how the Lumaprints API works and what it does and doesn’t support. Use it with the API documentation at https://api-docs.lumaprints.com, which has the full endpoint reference. If your question isn’t answered here, email devs@lumaprints.com for API issues or contact@lumaprints.com for order concerns.

Key documentation pages

Topic	Link
API documentation home	https://api-docs.lumaprints.com
Sandbox Setup Guide	https://api-docs.lumaprints.com/doc-2394350
Authentication	https://api-docs.lumaprints.com/doc-420489
Sandbox test cards	https://api-docs.lumaprints.com/doc-421693
Submit order	https://api-docs.lumaprints.com/api-5384560
Webhooks	https://api-docs.lumaprints.com/doc-513534
Shipments (also the webhook payload format)	https://api-docs.lumaprints.com/api-5384566

1. Getting Started

What can I do with the Lumaprints API?

You can browse the product catalog, check images, get shipping costs, submit orders, look up orders, and get shipment information. The API is open to everyone.

Do you have a direct integration for my platform (Amazon, etc.)?

We have direct integrations for Shopify, Etsy, WooCommerce and Squarespace.

If your platform isn't on that list, check whether it connects to ShipStation or Order Desk. Both work with Lumaprints, and both connect to many other sales channels and marketplaces. They act as a bridge: orders come from your platform into ShipStation or Order Desk, go to Lumaprints for fulfillment, and the shipment details go back to your platform. You don't need to write any code.

If your platform doesn't work with either one, you or your developers can build the integration with the API. We don't build new direct integrations unless there is enough demand for one.

Will Lumaprints build the integration for me?

No. Your team builds and maintains the API integration. If you don't have developers, you may need to hire one, or use one of our direct integrations.

Should I use the Shopify app or the API?

If your store runs on Shopify, the Lumaprints Fulfillment app syncs orders for you, so you don't need to write any code. Use the API when you have a custom storefront, need full control over order submission, or run a platform with no direct integration.

How do I get support?

API issues (integration, endpoints, errors, keys): email devs@lumaprints.com. The team replies on weekdays and is off on weekends unless monitoring detects a system issue.

Order concerns (cancellations, order status, shipping, print quality, remakes): email contact@lumaprints.com with the order number.

2. Stores and Store IDs

Which store types can submit orders through the API?

Only Standard Stores. API order creation does not work for stores connected through a direct integration (WooCommerce, Shopify, etc.), because those orders sync automatically.

`GET /stores` doesn't return my WooCommerce (or other connected) store. How do I get its storeId?

Connected stores are not returned because they can't be used for API order creation. If you want to submit orders through the API, create or use a Standard Store and use its storeId.

3. Sandbox

Register at https://sandbox.lumaprints.com/account/register. You don't need to sign in with Google. The sandbox is separate from production, so it needs its own registration even if you use the same email.

What are the sandbox and production URLs?

	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
Orders fulfilled	No	Yes
Cards charged	No (test cards only)	Yes

What can I test in the sandbox?

Authentication, catalog lookups, image checks, shipping pricing and order payloads.

What does NOT work in the sandbox?

Connected store integrations (Shopify, WooCommerce, etc.) don't work there.

Order status doesn't progress. Orders stay in their first status.

Because orders never ship, GET /shipments/{orderNumber} returns no data and shipping webhooks don't fire.

Can I submit test orders to production?

No. Every production order is printed, charged and shipped. Submitting test orders to production results in permanent revocation of API access.

Can I place paid proof orders in production to check quality?

Yes. A paid order you want printed and shipped to yourself is a real order, not a test order, so it can go through the production API. The sandbox rule only covers orders submitted just to test the integration. You don't need a special prefix on these orders.

What do I need to change when going live?

Create a Standard Store and add a primary payment method and default billing address.

Generate production API keys.

Switch the base URL to https://us.api.lumaprints.com/api/v1.

Call GET /stores with your production keys to get your production storeId. Sandbox storeIds don't exist in production.

Set up your webhook again in production. Webhook settings don't carry over.

4. Authentication and API Keys

How do I authenticate?

Use HTTP Basic authentication with your API key and secret (apiKey:apiSecret, Base64-encoded, prefixed with Basic ). See Authentication.

I lost my API secret. Can I view it again?

No. The secret is shown only once when the key is created. Generate a new key.

Are API keys tied to the user who created them?

No. Keys are organization-wide. A key works the same no matter which user on the account created it.

Do you offer read-only API keys?

No. Every key has full access to all API features, including order submission.

The account owner can create a custom user role with permission to view and manage the Developer section, then invite the developer with that role. We recommend this over emailing credentials.

Why can't I generate API keys?

The API Keys page requires the account setup to be complete first, including a Standard Store, a primary payment method and a default billing address.

5. Products, Pricing and Catalog

Can you send a CSV price list?

No. There are thousands of product and option combinations, so a static file isn't practical. Get prices from the pricing endpoints instead.

Where can I get product mockups?

Mockups can be downloaded from the bottom of the product pages on our website, for example https://www.lumaprints.com/canvas-prints/.

Is there a `/sizes` endpoint?

No. Use the categories, subcategories and subcategory options endpoints to get product configuration. Only use the endpoints listed in the API documentation.

Is there a frame, size and media availability matrix?

No. Each subcategory has a maximum size limit, and the ordered size cannot go over it.

Does the mat count toward the maximum size?

Yes. For example, a 24x36 print with a 2 in mat is checked as 28x40.

What does "Required" mean for the `options` property?

The options property must be in the payload. An empty array uses the default options. There is no document listing the defaults, but they are the options already selected in the website image editor after you choose a size.

Can I use decimal sizes like 16.5x21?

Yes. Both POST /pricing/shipping and POST /orders accept decimal width and height. The documentation saying /pricing/shipping needs integers is wrong.

6. Images and Files

Which image formats are supported?

JPG and PNG, up to 100MB per file.

Which color profile should I use?

We print in Adobe RGB. Images in other color profiles are converted to Adobe RGB, which may cause a color shift in the final print. To get the most accurate colors, send your images in Adobe RGB.

Can I upload files directly to the API?

No. The API takes image URLs only. We download the file from the URL you send.

How long must my image URL stay accessible?

At least 30 minutes after you submit the order. We keep our own copy of the image for at least 30 days for remakes.

Can I use signed or pre-signed URLs?

Yes. The full URL, including the query string, counts toward the 1,024-character URL limit.

What IP addresses or user agent do you download images from?

There is no fixed IP range. Image downloads run on serverless infrastructure across different providers, using a generic user agent. Failed downloads are retried 3 times with backoff. There is no timeout on the download itself, but your file server must respond within 30 seconds.

I updated my artwork but the old file was printed.

Files are cached by URL. When you update an artwork, publish it under a new URL instead of overwriting the old file.

Are API images added to my Image Library?

No. Images submitted through the API are not added to the Image Library.

Do I need to crop images before submitting?

The file is fitted automatically using the size and options in your payload, so the file you send is what gets printed. The image's aspect ratio must match the ordered size within a 1% tolerance. Check your file before ordering with POST /images/checkImageConfig.

Why do the print dimensions look different on your side?

Some products add bleed or wrap to the print size, depending on the product and options (for example, canvas wraps). Check the product's requirements in the documentation.

What file do I need for canvas wraps?

Mirror Wrap: send only the front of the image. We mirror the edges.

Image Wrap: the file must include the side bleed.

Can I see where my image is placed on an API order?

No. Image placement can't be viewed for API orders. GET /orders/{orderNumber} returns the file URL on each item if you want to check what is attached.

My AI-generated images are low resolution. What should I do?

AI-generated images are often too low resolution for large prints. Limit which print sizes you offer, or check resolution with POST /images/checkImageConfig before showing size options to your customers. Unique images on every order are fine.

Do you display customer artwork in a gallery?

No. Lumaprints no longer displays customer artwork in a gallery.

7. Orders

What checks run when I submit an order?

Before accepting an order, POST /orders checks things like whether the address is provided, the image URL is accessible, the file meets the size requirements, and the shipping method and production time are available. If a check fails, the request is rejected with an error. A successful response means the order passed those checks and was accepted.

Why is my new order in "Pending Payment"?

Orders charge the store's primary payment method right after submission. An order moves to Awaiting Fulfillment only after the account is charged successfully.

What are the order statuses?

Status	Meaning
Pending Payment	The order was accepted and is waiting for a successful charge
Awaiting Fulfillment	Payment succeeded and the order is in production
Shipped	The order has shipped
Canceled	The order was canceled

Can I create a draft or put an order on hold?

No. There is no draft or hold option in the API, and there are no plans to add a two-step workflow. Hold orders on your side and submit them once your hold period is over. Make sure the artwork is final before you submit.

Can I edit or cancel an order through the API?

No. Orders can't be edited once placed, on the website or through the API. An API order counts as placed as soon as it is submitted. There are no plans to add cancellation or address changes to the API.

How do I request a cancellation?

Email contact@lumaprints.com with the order number as early as possible. There is no guaranteed window, because time to production varies.

Is `externalId` unique?

Yes, per store. An order with a duplicate externalId is rejected instead of creating a duplicate order.

Is there a limit on items per order?

No. There is no item limit, and you can mix any subcategories in one order.

Do you validate addresses on submission?

No. Addresses are validated internally after submission. Our customer service team contacts you if an address needs checking or a parcel is returned.

Can I add a gift note?

Yes. Send the note as a printout file (a one-page PDF works well). Don't use specialInstructions for gift notes. That field is for our production team.

The API rejected my payload, but I followed an example.

Compare your payload with the Submit order reference at https://api-docs.lumaprints.com/api-5384560. Only the fields and structure shown there are supported. If it still fails, send us the full request payload and the error response.

8. Printouts and Packaging

What are printouts?

Extra documents such as branded inserts, thank-you cards or gift notes. They are printed and packed in the box with the order.

What are the printout limits?

Up to 3 printed pages per order in total, across all printout files (a 2-page PDF leaves room for one more 1-page printout)

Max 5MB per file

Printed single-sided on 8.5x11 regular paper

Do printouts cost extra?

No.

Are shipments white-labeled?

Yes, by default, with nothing to set up. The shipping label shows your store name, and no Lumaprints promotional materials go in the package.

Do you include a packing slip?

No.

What are the specs for a logo on the back of a canvas?

At least 1" tall, max 2" wide, 200 DPI. A PNG with a transparent background is recommended.

9. Shipping

Which shipping method codes can I use?

Every shipping method code returned by the shipping cost endpoint is valid in POST /orders, even if it's missing from the documentation list.

Which methods can I use for US express orders?

usps_priority_mail_express, 2_day or overnight.

Is there a transit-days endpoint or zone table?

No. Carriers don't always return transit days, and an order's production site can change (for example, when a site has delays or inventory issues), so the ship-from location isn't fixed. Show arrives-by dates to your customers as an estimated range, not a fixed date.

Which carrier values can appear in shipment data?

FedEx, Pickup, USPS, GLS, Freight, UPS, DHL.

Do multiple shipments for one order show up together?

GET /shipments/{orderNumber} returns all shipments for the order.

10. Webhooks and Status Updates

Which webhook events are available?

Shipping is the only event. There are no events for accepted, in production, canceled or on hold, and none are planned soon. Problems like a missing address or an unavailable shipping method are caught when the order is submitted, so they don't need an event.

What does the shipping webhook payload look like?

It is exactly the same as the GET /shipments/{orderNumber} response. See https://api-docs.lumaprints.com/api-5384566.

Are webhooks retried?

No. Each event is sent once and is not retried on a non-2xx response. Poll GET /shipments/{orderNumber} as a fallback for orders where you haven't received a shipping event.

How often should I poll for shipments?

Once every 30 minutes.

Are webhook payloads signed?

No, payload signing isn't available.

What does the webhook "test" button send?

A plain POST with no event payload. It only checks that your URL exists and accepts POST. We don't send a real payload because it could trigger shipment notices on your side.

I use Order Desk. Why am I not getting shipment updates?

Order Desk gives you a Shipment Webhook URL that has to be set in your Lumaprints account. We can't know that URL ahead of time. If it wasn't set during setup, add it yourself in the Developer section of the Lumaprints dashboard.

11. Rate Limits and Logs

What is the rate limit?

40 calls per minute per API key. Each key has its own limit.

Can I get a higher rate limit?

You can ask. We review whether a higher limit makes sense, or whether your API usage can be improved instead. Using the shipping webhook and the list endpoint instead of polling orders one by one helps a lot.

Is there a request log I can check?

No. There is no API request log for integrators. Log your requests and responses on your side.

12. Billing and Payments

How are API orders billed?

Each order is charged on its own for its orderTotal, using the store's primary payment method.

Why was my order rejected for a missing payment method?

The store has no primary payment method or default billing address. Add both and try again.

What happens if my card is declined?

The charge is retried. If every retry fails, the account is locked and we email you. Update the card to continue.

Where are card details stored?

Only in Braintree, our payment processor. Lumaprints stores just the transaction ID and card ID.

Can the same card be used on two Lumaprints accounts?

No. A card can be saved on only one account at a time. Remove it from the other account first.

1. Getting Started#

What can I do with the Lumaprints API?#

Do you have a direct integration for my platform (Amazon, etc.)?#

Will Lumaprints build the integration for me?#

Should I use the Shopify app or the API?#

How do I get support?#

2. Stores and Store IDs#

Which store types can submit orders through the API?#

GET /stores doesn't return my WooCommerce (or other connected) store. How do I get its storeId?#

3. Sandbox#

How do I sign up for the sandbox?#

What are the sandbox and production URLs?#

What can I test in the sandbox?#

What does NOT work in the sandbox?#

Can I submit test orders to production?#

Can I place paid proof orders in production to check quality?#

What do I need to change when going live?#

4. Authentication and API Keys#

How do I authenticate?#

I lost my API secret. Can I view it again?#

Are API keys tied to the user who created them?#

Do you offer read-only API keys?#

How do I give an outside developer access without sharing my login?#

Why can't I generate API keys?#

5. Products, Pricing and Catalog#

Can you send a CSV price list?#

Where can I get product mockups?#

Is there a /sizes endpoint?#

Is there a frame, size and media availability matrix?#

Does the mat count toward the maximum size?#

What does "Required" mean for the options property?#

Can I use decimal sizes like 16.5x21?#

6. Images and Files#

Which image formats are supported?#

Which color profile should I use?#

Can I upload files directly to the API?#

How long must my image URL stay accessible?#

Can I use signed or pre-signed URLs?#

What IP addresses or user agent do you download images from?#

I updated my artwork but the old file was printed.#

Are API images added to my Image Library?#

Do I need to crop images before submitting?#

Why do the print dimensions look different on your side?#

What file do I need for canvas wraps?#

Can I see where my image is placed on an API order?#

My AI-generated images are low resolution. What should I do?#

Do you display customer artwork in a gallery?#

7. Orders#

What checks run when I submit an order?#

Why is my new order in "Pending Payment"?#

What are the order statuses?#

Can I create a draft or put an order on hold?#

Can I edit or cancel an order through the API?#

How do I request a cancellation?#

Is externalId unique?#

Is there a limit on items per order?#

Do you validate addresses on submission?#

Can I add a gift note?#

The API rejected my payload, but I followed an example.#

8. Printouts and Packaging#

What are printouts?#

What are the printout limits?#

Do printouts cost extra?#

Are shipments white-labeled?#

Do you include a packing slip?#

What are the specs for a logo on the back of a canvas?#

9. Shipping#

Which shipping method codes can I use?#

Which methods can I use for US express orders?#

Is there a transit-days endpoint or zone table?#

Which carrier values can appear in shipment data?#

Do multiple shipments for one order show up together?#

10. Webhooks and Status Updates#

Which webhook events are available?#

What does the shipping webhook payload look like?#

Are webhooks retried?#

How often should I poll for shipments?#

Are webhook payloads signed?#

What does the webhook "test" button send?#