Orders

An order is a group of printable products that RPI prints and ships to a single destination address.

Each order item specifies one of your products by its product SKU, sent as sku. An item whose sku matches none of your products fails validation.

You can fetch the available shipping options and the price of an order through the API without creating the order.

Orders are validated on submission. A malformed request, or one to an unsupported country, is refused with HTTP 400 and no order is created. Other problems, such as a shipping tier the destination does not offer or a missing retailPrice, do not refuse the request: it returns 201, the order moves to FAILED, and RPI Print API sends the OrderValidationFailed webhook.

Customer Order Ids

When creating an order you can include an optional customerOrderId of up to 40 characters. If you do not send one, RPI Print API generates one for the order. This is the identifier you use in API requests and responses, and it appears under the Customer Order ID column in the RPI Print API Dashboard.

Specifying a customerOrderId does not make order creation idempotent. A second create request carrying a customerOrderId you have already used is rejected with HTTP 400 and a message naming the identifier. It neither creates a second order nor returns the first one.

This matters when a create request fails without telling you whether it succeeded, such as a network timeout. Retrying it blindly gives you a 400 that does not distinguish "your first attempt worked" from "that identifier is used by an unrelated older order". Call GET /orders/{customerOrderId} with the same API key to find out which. If it returns the order, your first attempt succeeded. If it returns 404, the identifier belongs to an order in your other mode (sandbox or production). Choose a new identifier rather than retrying with this one.

A customerOrderId must be unique across sandbox and production. The identifiers you use while testing in sandbox are therefore not available to your production orders.

Payload

When creating an order you can include an optional payload field of up to 512 characters. RPI Print API returns this string in every webhook and every GET response for the order, so you can use it to match orders to records in your own system.

Holding bin

Orders enter the holding bin after payment is processed. RPI Print API holds them there for 2 hours before sending them to the printer. The hold gives you a window to cancel an order, for example when your own customer cancels it with you.

A cancel request for an order in the holding bin cancels it. Once an order leaves the holding bin, RPI Print API forwards a cancel request to the printer, and the printer may reject it. You can send a cancel request until the order ships, except while its status is VALIDATING, CANCELLATION_REQUESTED or EXCEPTION; see Order states.

Tracking numbers

When the printer ships the order, the order moves to SHIPPED and RPI Print API sends the OrderShipped webhook. The order's shipmentTracking field then lists the tracking details. The field is part of the order object that every webhook carries, starting with that OrderShipped webhook, and of the order that GET /orders/{customerOrderId} returns. Each entry groups the packages that share a master tracking number. Each package has a trackingNumber, an altTrackingNumber for carriers that assign two, and a trackingUrl that links to the carrier's tracking page. RPI records tracking once, when the whole order has shipped, so shipmentTracking is empty until then. A field can be empty when the carrier provided no value.

When an Enterprise order shows its amounts

An Enterprise order shows its amounts once the printer has priced them, and shows none before then. RPI does not charge an Enterprise account through RPI Print API, so the printer sets the price, and it does so in two steps. It prices the items when it accepts the order, and it prices the shipping when the order ships.

Until that pricing arrives, the order responses and webhooks for the order report the amounts as follows:

• The pricing block is absent until the items have been priced. Once they have, it carries itemsTotal and taxesTotal.
• pricing.shippingTotal and selectedShipping.price are null until the shipping has been priced.
• pricing.orderTotal and paymentInfo.total are null until both the items and the shipping have been priced.

Read null as "not priced yet", not as zero. Orders on an account that RPI Print API charges are not affected by these rules.

Limits and quotas

Daily order limit

By default, an account can create 50 orders in any rolling 24-hour period. Customer support can change this limit for your account. To ask for a different limit, email printapicustomersupport@rpiprint.com.

Reprints do not count toward the limit.

RPI Print API accepts an order created over the limit with HTTP 201 and moves it to QUEUED. It releases queued orders as the rolling 24-hour limit allows. A released order moves to RECEIVED and continues processing.

The queue has a ceiling of 350 orders by default. The ceiling counts the orders received in the last 24 hours and the orders waiting in the queue together, so with the default limit up to 300 orders can wait. RPI Print API still accepts an order past the ceiling with HTTP 201, then moves it to REJECTED and sends the OrderExceedsLimitQueue webhook. A rejected order is not processed.

In sandbox, an order over the limit moves to REJECTED immediately and is never queued.

For example, if you create 420 orders within 24 hours with the default settings:

• The first 50 orders are RECEIVED and continue processing.
• The next 300 orders are QUEUED, and RPI Print API releases them as the limit allows.
• The last 70 orders are REJECTED.