Preview an order checkout
Calculates the line-item cost, production, and estimated delivery details for an order so they can be reviewed before checking out. This preview is side-effect-free: it does not modify the order and does not create a payment intent. Calling this endpoint is not required before executing a checkout. Pass `autoBill=false` to preview the checkout under the payment-method opt-out: if the available account balance does not cover the order in full the preview is rejected with HTTP 402 Payment Required and error code INSUFFICIENT_BALANCE — the exact rejection the checkout execute verb returns for the same order — so a preview and an execute agree on whether the order can proceed. The preview remains side-effect-free even when rejected.
Calculates the line-item cost, production, and estimated delivery details for an order so they can be reviewed before checking out. This preview is side-effect-free: it does not modify the order and does not create a payment intent. Calling this endpoint is not required before executing a checkout. Pass autoBill=false to preview the checkout under the payment-method opt-out: if the available account balance does not cover the order in full the preview is rejected with HTTP 402 Payment Required and error code INSUFFICIENT_BALANCE — the exact rejection the checkout execute verb returns for the same order — so a preview and an execute agree on whether the order can proceed. The preview remains side-effect-free even when rejected.
Authorization
ApiKey In: header
Path Parameters
The Id of the order to calculate checkout details.
Query Parameters
The type of postage for the order. Available values: Standard, FirstClass. Also accepted as PostageType, the name the checkout execute body uses for the same input.
The speed of production for the order. Available values: Normal, ExpeditedFaster, ExpeditedFastest. Also accepted as ProductionSpeed, the name the checkout execute body uses for the same input.
The date to hold order production until. This date must be further in the future than the normal estimated production completion date. Query parameter names are matched case-insensitively, so the execute body's HoldUntilDate spelling has always been accepted here.
Whether the checkout being previewed may charge the account's default payment method for any amount not covered by the available balance. Available values: true, false. Defaults to true. Sending false requires the balance to cover the order in full and otherwise rejects the preview with HTTP 402 Payment Required and error code INSUFFICIENT_BALANCE — the same rejection the checkout execute verb returns for its autoBill body field — so a preview and an execute of the same order agree. The preview stays side-effect-free regardless.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/order/0/checkout"{ "profile": { "id": 0, "aadId": "1cbad290-069a-4527-be23-a0c144b5302d", "email": "string", "firstName": "string", "lastName": "string", "company": "string", "created": "2019-08-24T14:15:22Z", "shouldProcessQrCodes": true }, "payload": { "orderId": 0, "status": "Success", "lineItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "credits": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "totalCharges": 0.1, "totalTax": 0.1, "totalCredits": 0.1, "balance": 0.1, "productionSpeeds": { "Normal": "2019-08-24T14:15:22Z", "ExpeditedFaster": "2019-08-24T14:15:22Z", "ExpeditedFastest": "2019-08-24T14:15:22Z", "HailTrace": "2019-08-24T14:15:22Z" }, "productionSpeedPrices": { "property1": 0.1, "property2": 0.1 }, "postageTypePrices": { "property1": 0.1, "property2": 0.1 }, "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z", "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z" }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "profile": { "id": 0, "aadId": "1cbad290-069a-4527-be23-a0c144b5302d", "email": "string", "firstName": "string", "lastName": "string", "company": "string", "created": "2019-08-24T14:15:22Z", "shouldProcessQrCodes": true }, "payload": { "orderId": 0, "status": "Success", "lineItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "credits": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "totalCharges": 0.1, "totalTax": 0.1, "totalCredits": 0.1, "balance": 0.1, "productionSpeeds": { "Normal": "2019-08-24T14:15:22Z", "ExpeditedFaster": "2019-08-24T14:15:22Z", "ExpeditedFastest": "2019-08-24T14:15:22Z", "HailTrace": "2019-08-24T14:15:22Z" }, "productionSpeedPrices": { "property1": 0.1, "property2": 0.1 }, "postageTypePrices": { "property1": 0.1, "property2": 0.1 }, "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z", "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z" }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "profile": { "id": 0, "aadId": "1cbad290-069a-4527-be23-a0c144b5302d", "email": "string", "firstName": "string", "lastName": "string", "company": "string", "created": "2019-08-24T14:15:22Z", "shouldProcessQrCodes": true }, "payload": { "orderId": 0, "status": "Success", "lineItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "credits": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "totalCharges": 0.1, "totalTax": 0.1, "totalCredits": 0.1, "balance": 0.1, "productionSpeeds": { "Normal": "2019-08-24T14:15:22Z", "ExpeditedFaster": "2019-08-24T14:15:22Z", "ExpeditedFastest": "2019-08-24T14:15:22Z", "HailTrace": "2019-08-24T14:15:22Z" }, "productionSpeedPrices": { "property1": 0.1, "property2": 0.1 }, "postageTypePrices": { "property1": 0.1, "property2": 0.1 }, "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z", "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z" }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "profile": { "id": 0, "aadId": "1cbad290-069a-4527-be23-a0c144b5302d", "email": "string", "firstName": "string", "lastName": "string", "company": "string", "created": "2019-08-24T14:15:22Z", "shouldProcessQrCodes": true }, "payload": { "orderId": 0, "status": "Success", "lineItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "credits": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "totalCharges": 0.1, "totalTax": 0.1, "totalCredits": 0.1, "balance": 0.1, "productionSpeeds": { "Normal": "2019-08-24T14:15:22Z", "ExpeditedFaster": "2019-08-24T14:15:22Z", "ExpeditedFastest": "2019-08-24T14:15:22Z", "HailTrace": "2019-08-24T14:15:22Z" }, "productionSpeedPrices": { "property1": 0.1, "property2": 0.1 }, "postageTypePrices": { "property1": 0.1, "property2": 0.1 }, "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z", "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z" }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "profile": { "id": 0, "aadId": "1cbad290-069a-4527-be23-a0c144b5302d", "email": "string", "firstName": "string", "lastName": "string", "company": "string", "created": "2019-08-24T14:15:22Z", "shouldProcessQrCodes": true }, "payload": { "orderId": 0, "status": "Success", "lineItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "credits": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [ { "tax": 0.1, "name": "string", "quantity": 0, "rate": 0.1, "total": 0.1, "transactionType": "LineItemDebit", "transactionSubType": "HandWrittenPostCard", "subItems": [] } ] } ], "totalCharges": 0.1, "totalTax": 0.1, "totalCredits": 0.1, "balance": 0.1, "productionSpeeds": { "Normal": "2019-08-24T14:15:22Z", "ExpeditedFaster": "2019-08-24T14:15:22Z", "ExpeditedFastest": "2019-08-24T14:15:22Z", "HailTrace": "2019-08-24T14:15:22Z" }, "productionSpeedPrices": { "property1": 0.1, "property2": 0.1 }, "postageTypePrices": { "property1": 0.1, "property2": 0.1 }, "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z", "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z" }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}List orders GET
Returns the account's orders with their status, product, postage, and delivery progress. Supports the id, status, paid, product, postage, and showRecipients filters, plus pageNumber/pageSize pagination.
Execute an order checkout POST
Submits an order for production with the supplied postage type, production speed, and optional hold-until date, and accepts it for payment. Payment settles asynchronously, so a 200 means the checkout was ACCEPTED, not that the order has been charged: the response reports the order's resulting status in "orderStatus", when to start polling in "pollAfterSeconds", and when settlement is expected to have reached a terminal state in "settlementExpectedWithinSeconds" — size your polling from those rather than a bound of your own. On acceptance the order moves to "Payment Needed" immediately and stops being editable: recipient changes, order deletion, and further checkouts return 400 while payment settles. The order then reads "Paid" once settlement completes, or returns to "Draft" if payment fails (retry by checking out again). Never retry a checkout that returned 200 — the charge is already in flight, and a second checkout charges again.