> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/api/orders-api/orders.md).

# Orders

Submit or preview orders to trigger Limio's order orchestration framework. Supports new subscriptions, offer changes, cancellations, address updates, payment method changes, and gift redemptions.

## Submit Order

> Submit an order. \`order\_type\` selects what the order does, and the rest of the body is the payload of that type. This one endpoint therefore covers most of what happens to a subscription after it starts.\
> \
> Buy a new subscription with \`new\`. Cancel one with \`cancel\_subscription\`, and refund it with \`refund\`. Change what the customer has with \`change\_offer\`, \`add\_offer\` or \`update\_subscription\`. Change their details with \`change\_address\` or \`update\_customer\_details\`. Change how they pay with \`change\_payment\`, \`change\_default\_payment\` or \`delete\_payment\_method\`. Record an answer they gave with \`data\_capture\`.\
> \
> Send the same body to \`/order/preview\` first to see the totals, the taxes and the schedule that the order would produce, without submitting it.\
> \
> If the order is created but immediate processing fails, the response keeps HTTP 200 and adds \`error\_reason\` plus either a \`payment\` or \`processing\` section describing what went wrong and whether it is worth retrying.\
> \
> Optionally include a partner organisation to attribute the order to, run partner-specific eligibility checks, and associate the order and all its related objects with the partner organisation.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Submit or preview orders to trigger Limio's order orchestration framework. Supports new subscriptions, offer changes, cancellations, address updates, payment method changes, and gift redemptions."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"AdminOrderExtension":{"type":"object","description":"Additional fields available when submitting an order as an admin user.","properties":{"forPartner":{"description":"Submit the order on behalf of a specific partner organisation.","allOf":[{"$ref":"#/components/schemas/AdminOrderPartner"}]}}},"AdminOrderPartner":{"type":"object","description":"Partner organisation to associate with the order and all related objects. The end customer will be the subscription owner.","properties":{"id":{"type":"string","description":"Partner organisation id"}},"required":["id"]},"CreateSubscription":{"type":"object","title":"Create Subscription","description":"Create a new subscription","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["new"]},"orderItems":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"}}}},"orderDiscount":{"$ref":"#/components/schemas/OrderDiscount"},"billingDetails":{"$ref":"#/components/schemas/Address"},"deliveryDetails":{"$ref":"#/components/schemas/Address"},"customerDetails":{"$ref":"#/components/schemas/CustomerDetails"},"tracking":{"$ref":"#/components/schemas/Tracking"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"orderDate":{"type":"string","format":"date-time","description":"the date on which the subscription should start"},"checkoutId":{"type":"string","description":"the limio session checkout id for this order"},"country":{"type":"string","description":"the country code of the customer's purchase location"}},"required":["order_type","billingDetails","customerDetails","orderItems","payment","country","checkoutId"]}]},"Order":{"type":"object","description":"Common order properties shared across all order types. These fields can be included alongside the order-type-specific payload (e.g. CreateSubscription, ChangeOffer).","properties":{"external_id":{"description":"Your own external order reference. Useful for correlating Limio orders with records in upstream systems.","type":"string"},"initiated_source":{"description":"Indicates where the order originated. Limio uses `shop` for storefront orders and `salesforce` for CRM-initiated orders. Custom values are supported for other integrations.","type":"string","enum":["shop","salesforce"]},"source":{"description":"The system that submitted the order. Limio uses `shop` for storefront submissions and `salesforce` for CRM submissions.","type":"string"},"process_immediately":{"description":"When `true`, the order is processed synchronously and the response includes the final processing result. When `false` (default), the order is queued for asynchronous processing.","type":"boolean","default":false}}},"OfferPayload":{"description":"Reference to a published Limio offer.\nRetrieve `id` and `version` from `GET /offers/v2`.\n","required":["id","version"],"properties":{"id":{"type":"string","description":"The unique content hash of the offer. Retrieve from `GET /offers/v2`."},"version":{"type":"string","description":"The version hash of the offer. Use the latest version from the same API response."}}},"OrderDiscount":{"description":"Order Discount","type":"object","properties":{"name":{"type":"string","description":"The name of the order discount"},"productDetails":{"type":"object","properties":{"ratePlan":{"type":"object","properties":{"path":{"type":"string","description":"The path of the rate plan"}}},"product":{"type":"object","properties":{"path":{"type":"string","description":"The path of the product"}}}}},"product":{"$ref":"#/components/schemas/ProductDetails"},"discountOverrides":{"type":"object","properties":{"discountType":{"type":"string","description":"The type of the discount"},"durationLength":{"type":"number","description":"The period of time the discount is applied"},"durationType":{"type":"string","description":"The type of period of time the discount is applied"},"percentageDiscount":{"type":"number","description":"The percentage of the discount"},"amountDiscount":{"type":"number","description":"The amount of the discount"},"currency":{"type":"string","description":"The currency of the discount"},"orderItemsWithSpecifiedDiscount":{"type":"object","properties":{"discountedOffers":{"type":"array"}}}}}}},"ProductDetails":{"type":"object","properties":{"baseTemplate":{"type":"string"},"entitlements":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}},"path":{"type":"string"},"created":{"type":"string","format":"date-time"},"modified":{"type":"string","format":"date-time"},"attributes":{"$ref":"#/components/schemas/ProductAttributes"},"record_type":{"type":"string"},"lastSynced":{"type":"string","format":"date-time"},"synced":{"type":"boolean"},"syncedFrom":{"type":"string"}}},"Entitlement":{"type":"object","properties":{"$ref":{"type":"string"}}},"ProductAttributes":{"type":"object","properties":{"display_name__limio":{"type":"string"},"has_delivery__limio":{"type":"boolean"},"product_code__limio":{"type":"string"}}},"Address":{"description":"Address","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"workEmail":{"type":"string"},"phone":{"type":"string"},"workPhone":{"type":"string"},"otherPhone":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}},"CustomerDetails":{"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}},"Tracking":{"type":"object","description":"Tracking data associated with the order, used for attribution and integration with external systems. When the basket resolves an owner, the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows. An owner is resolved from `accountId` or `zuoraAccountNumber` here, or from a renewal `subscriptionId` on the order itself.","properties":{"offers":{"type":"array","items":{"type":"string"}},"purchaseCountryCode":{"type":"string"},"accountId":{"type":"string","description":"Salesforce Account ID. When provided, Limio resolves or creates an identity owner for the basket and returns an `assistedCheckoutLink` in the response."},"zuoraAccountNumber":{"type":"string","description":"Zuora account number. Like `accountId`, resolves an identity owner for the basket, so the response includes an `assistedCheckoutLink`. `accountId` takes precedence when both are provided."},"contactId":{"type":"string","description":"Salesforce Contact ID associated with this order."},"userId":{"type":"string","description":"Salesforce User ID associated with this order."}}},"ZuoraPayment":{"type":"object","description":"Zuora Payment Method","properties":{"type":{"type":"string","enum":["zuora"]},"zuora":{"type":"object","properties":{"refId":{"type":"string","description":"The Zuora ID of the payment method to use for the payment"},"paymentGateway":{"type":"string","description":"The Zuora payment gateway to use for processing the payment"}}}}},"CreateGiftSubscription":{"type":"object","title":"Create Gift Subscription","description":"Create a new gift subscription","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["new"]},"orderItems":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"}}}},"orderDiscount":{"$ref":"#/components/schemas/OrderDiscount"},"billingDetails":{"$ref":"#/components/schemas/Address"},"deliveryDetails":{"$ref":"#/components/schemas/Address"},"customerDetails":{"$ref":"#/components/schemas/CustomerDetails"},"tracking":{"$ref":"#/components/schemas/Tracking"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"orderDate":{"type":"string","format":"date-time","description":"the date on which the subscription should start"},"checkoutId":{"type":"string","description":"the limio session checkout id for this order"},"country":{"type":"string","description":"the country code of the customer's purchase location"},"isRedeem":{"type":"boolean"},"recipientDetails":{"$ref":"#/components/schemas/RecipientDetails"},"isGift":{"type":"boolean","enum":[true]},"variant":{"type":"string","enum":["gift"]}},"required":["order_type","billingDetails","customerDetails","orderItems","payment","country","recipientDetails","isGift","variant"]}]},"RecipientDetails":{"type":"object","properties":{"startNow":{"type":"boolean","description":"if true, the gift subscription will begin on the date of the order, not when the gift is redeemed by the recipient"},"startDate":{"type":"string","format":"date-time","description":"send the gift on a specific date, will default to the order date if undefined"},"firstName":{"type":"string"},"lastName":{"type":"string"},"sendEmail":{"type":"boolean","description":"a flag that the order keeps for your email system. Limio does not send the gift email"},"message":{"type":"string","description":"a message from the purchaser to the recipient"},"email":{"type":"string","format":"email"}},"required":["email"]},"RedeemGiftSubscription":{"type":"object","title":"Redeem Gift Subscription","description":"Redeem a new gift subscription","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["new"]},"orderItems":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"}}}},"deliveryDetails":{"$ref":"#/components/schemas/Address"},"customerDetails":{"$ref":"#/components/schemas/CustomerDetails"},"orderDate":{"type":"string","format":"date-time","description":"the date on which the subscription should start"},"giftCode":{"type":"string","description":"gift code a recipient redeems their gift with"},"payment":{"description":"Payment","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"type of payment method","enum":["gift_code"]},"gift_code":{"type":"string","description":"gift code a recipient redeems their gift with"}}},"tracking":{"type":"object","properties":{"accountId":{"type":"string"},"contactId":{"type":"string"}}},"sourceDetails":{"type":"object","properties":{"instance":{"type":"string"}}},"checkoutId":{"type":"string","description":"the limio session checkout id for this order"},"country":{"type":"string","description":"the country code of the customer's purchase location"},"recipientDetails":{"$ref":"#/components/schemas/RecipientDetails"},"hasDelivery":{"type":"boolean"}},"required":["order_type","customerDetails","orderItems","payment","country","recipientDetails","giftCode"]}]},"ChangeOffer":{"type":"object","title":"Change Offer","description":"Change the offer that is attached to a subscription.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["change_offer"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"offer":{"$ref":"#/components/schemas/OfferPayload"},"effectiveDate":{"description":"The date on which the Offer change will be effective. If not provided, the change will be effective at the end of the current term.","type":"string","format":"date-time"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"billingDetails":{"$ref":"#/components/schemas/Address"},"deliveryDetails":{"$ref":"#/components/schemas/Address"}},"required":["order_type","forSubscription","offer"]}]},"SubscriptionByName":{"description":"Update subscription by name","properties":{"name":{"type":"string"}}},"SubscriptionById":{"description":"Update subscription by id","properties":{"id":{"type":"string"}}},"AddOffer":{"type":"object","title":"Add Offer","description":"Replace the offer attached to a subscription with a discounted offer.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["add_offer"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"offer":{"$ref":"#/components/schemas/OfferPayload"},"effectiveDate":{"description":"The date on which the Offer change will be effective. If not provided, the change will be effective at the end of the current term.","type":"string","format":"date-time"}},"required":["order_type","forSubscription","offer"]}]},"CancelSubscription":{"type":"object","title":"Cancel Subscription","description":"Cancel a subscription.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["cancel_subscription"]},"forSubscription":{"description":"Subscription to cancel","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"effectiveDate":{"description":"The date on which the cancellation will be effective. If not provided, the cancellation will be effective at the end of the current term.","type":"string","format":"date-time"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"data":{"$ref":"#/components/schemas/CancelData"}},"required":["order_type","forSubscription"]}]},"CancelData":{"type":"object","description":"Cancel reasons data","properties":{"reason":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for the cancellation reason"}},"required":["id"]}}},"Refund":{"type":"object","title":"Refund","description":"Refund an order. Supply a `gift_code` to refund a gift subscription. Limio raises a credit memo against the gift's original charges, refunds it, and marks the gift code as redeemed. Preview the refund amount first with the Preview Order endpoint using `order_type: gift_refund`.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["refund"]},"gift_code":{"type":"string","description":"Gift code to refund. Limio looks up the gift's Zuora charges from this code to build the credit memo."},"subscriptionId":{"type":"string","description":"ID of the gift subscription being refunded."},"total":{"type":"object","description":"Amount to refund, raised on the credit memo.","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}}},"required":["order_type","subscriptionId","gift_code","total"]}]},"UpdateSubscription":{"type":"object","title":"Update Subscription","description":"Update an existing subscription — upgrade or downgrade the primary offer, add or remove add-ons, or change quantities on existing items.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["update_subscription"]},"owner":{"type":"string","description":"The identity ID of the subscription owner."},"forSubscription":{"description":"The subscription to update. Must include `id` and/or `name`.","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"forSubscriptionOffer":{"description":"The subscription offer being changed. Used by the checkout flow to resolve the current active offer when multiple offers exist on the subscription. Optional when the subscription has only one active offer.","type":"object","properties":{"offerId":{"type":"string","description":"The ID of the subscription_offer object."}}},"orderItems":{"type":"array","description":"The list of changes to apply. Each item specifies an action (add, remove, or update) targeting an offer, add-on, or existing subscription item.","items":{"$ref":"#/components/schemas/UpdateSubscriptionOrderItem"}},"effectiveDate":{"type":"string","format":"date-time","description":"ISO 8601 date when the changes take effect. If omitted, the system calculates it automatically based on the direction of change — upgrades and additions are effective immediately, downgrades and removals are effective at the end of the current term."}},"required":["order_type","forSubscription","orderItems"]}]},"UpdateSubscriptionOrderItem":{"description":"A single action within an update_subscription order. Each item adds, removes, or updates an offer or add-on on the subscription.","type":"object","required":["id","orderItemActionType","offer"],"properties":{"id":{"type":"string","description":"Unique identifier for this order item (typically a UUID)."},"orderItemActionType":{"type":"string","enum":["add","remove","update"],"description":"The action to perform.\n- `add` — Add a new offer or add-on to the subscription.\n- `remove` — Remove an existing subscription offer or add-on.\n- `update` — Change the quantity of an existing subscription item."},"type":{"type":"string","enum":["offer","add_on","subscription_offer","subscription_add_on"],"description":"The record type of the target item.\n- `offer` / `add_on` — Used with `add` actions. References a catalog offer or add-on.\n- `subscription_offer` / `subscription_add_on` — Used with `remove` and `update` actions. References an existing item on the subscription."},"offer":{"type":"object","description":"Reference to the catalog item (for add) or subscription item (for remove/update).","required":["id","version"],"properties":{"id":{"type":"string","description":"For `add` actions: the catalog offer or add-on ID. For `remove`/`update` actions: the subscription_offer or subscription_add_on ID."},"version":{"type":"string","description":"The version of the referenced object."}}},"quantity":{"type":"integer","minimum":1,"description":"The target quantity. Only applicable for `update` actions on items that support quantity changes (offers with `allow_multibuy` or `recurringVolume` pricing). Must be a positive integer within the offer's configured bounds."}}},"ChangeAddress":{"type":"object","description":"Create a new billing or delivery address on a subscription.","title":"Change Address","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["change_address"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"type":{"type":"string","enum":["billing","delivery","all"]},"address":{"$ref":"#/components/schemas/Address"}},"required":["order_type","forSubscription","type","address"]}]},"UpdateCustomerDetails":{"type":"object","title":"Update Customer Details","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["update_customer_details"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"customerDetails":{"$ref":"#/components/schemas/CustomerDetails"}},"required":["order_type","forSubscription","customerDetails"]}]},"ChangePayment":{"type":"object","title":"Change Payment Method","description":"Change the payment method on an existing subscription.\n\nWhen submitted without a `payment` object, the order status is set to `pending-payment`.\nThis supports flows where the payment token is collected separately (e.g. via an MMA checkout basket with Stripe).\n\nWhen submitted with a `payment` object, the order is processed immediately with the new payment method.\n","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["change_payment"]},"forSubscription":{"description":"Subscription to update. At least one of `id` or `name` is required.","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"checkoutId":{"type":"string","description":"The basket ID from the MMA checkout flow, if applicable"},"tracking":{"type":"object","description":"Must include `accountId` or `contactId` to identify the customer when submitting via the Salesforce endpoint.","properties":{"accountId":{"type":"string","description":"Salesforce Account ID"},"contactId":{"type":"string","description":"Salesforce Contact ID"}},"anyOf":[{"required":["accountId"]},{"required":["contactId"]}]},"payment":{"type":"object","description":"Payment details for the new payment method. If omitted, the order is created with\n`pending-payment` status and the payment is collected asynchronously.\n","properties":{"type":{"type":"string","description":"The payment provider type","enum":["stripe","invoice"]},"stripe":{"type":"object","description":"Stripe-specific payment data. Required when `type` is `stripe`.","properties":{"intentId":{"type":"string","description":"Stripe SetupIntent ID"},"intentType":{"type":"string","description":"Intent type"},"paymentMethodId":{"type":"string","description":"The new Stripe payment method ID"},"connectedAccountId":{"type":"string","description":"Stripe Connect account ID"}}}}}},"required":["order_type","forSubscription"]}]},"ChangeDefaultZuoraPaymentMethod":{"type":"object","title":"Change Default Zuora Payment Method","description":"Change the default payment method for an account in Zuora and on the customer in Limio.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["change_default_payment"]},"customerId":{"type":"string"},"newDefaultPaymentId":{"type":"string"}},"required":["order_type","customerId","newDefaultPaymentId"]}]},"DeletePaymentMethod":{"type":"object","title":"Delete Payment Method","description":"Delete the payment method for an account in Zuora and in Limio.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["delete_payment_method"]},"customerId":{"type":"string"},"paymentMethodId":{"type":"string"}},"required":["order_type","customerId","paymentMethodId"]}]},"DataCapture":{"type":"object","title":"Data Capture","description":"Submit data captured from a Data Capture Form component. The order is standalone (it does not target a subscription) and is forwarded to configured integrations such as Salesforce.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["data_capture"]},"data":{"type":"object","description":"Free-form object containing the fields collected by the Data Capture Form. Keys and values are defined by the form configuration."}},"required":["order_type","data"]}]},"AdminOrderResponse":{"type":"object","title":"Admin Order Response","description":"Response from submitting an order with management credentials. On success it matches OrderResponse. When the order event was created but immediate processing failed, it additionally carries structured failure detail so the caller can decide what to do next. All failure fields are absent on success.","allOf":[{"$ref":"#/components/schemas/OrderResponse"},{"type":"object","properties":{"error_reason":{"type":"string","enum":["payment","processing"],"description":"Present only alongside `error`. Names the section that describes the failure: `payment` for a payment or gateway failure (see the `payment` object), or `processing` for any other processing failure (see the `processing` array)."},"payment":{"$ref":"#/components/schemas/PaymentResult"},"processing":{"type":"array","description":"Non-payment plugin failures during processing. Present when `error_reason` is `processing`.","items":{"$ref":"#/components/schemas/PluginError"}}}}]},"OrderResponse":{"type":"object","description":"Response returned after successfully submitting an order.","properties":{"id":{"type":"string","description":"Unique identifier of the created order."},"order_reference":{"type":"string","description":"Human-readable order reference code."},"status":{"type":"string","description":"Status of the order event at the time of the response. New submissions return `submitted`, or `pending-payment` when the order carries no payment details yet (new orders and payment changes that redirect to a payment provider). Resubmitting an order with an `external_id` that was already submitted returns the stored event's current status instead, which may reflect later processing."},"external_id":{"type":"string","description":"The external order reference provided in the request, if any."},"subscriptionReference":{"type":"string","description":"Reference code of the subscription created or modified by this order."},"owner":{"type":"string","description":"The identity ID that owns objects created by this order."},"customer_endpoint":{"type":"string","description":"The webhook endpoint configured for this order type in the `webhooks.order` setting, if any."},"error":{"type":"string","description":"Error message when the order event was created but immediate processing failed. Absent on success."}}},"PaymentResult":{"type":"object","title":"Payment Failure","description":"Detail of a payment or gateway failure. Present on the admin order response when `error_reason` is `payment`.","properties":{"processor":{"type":"string","description":"The payment processor or gateway that reported the failure."},"reason":{"type":"string","enum":["generic_decline","suspected_fraud","card_velocity_exceeded","authentication_required","payment_method_unavailable","invalid_request","processing_error"],"description":"Normalised decline reason, derived from the processor's response."},"processorError":{"type":"object","description":"The raw response from the payment processor, for reference.","properties":{"code":{"type":"string","description":"The processor's response code."},"message":{"type":"string","description":"The processor's response message."}}},"retry":{"type":"string","enum":["payment_method","none"],"description":"What the caller should do next. `payment_method` - ask the customer for a different card or payment method. `none` - do not retry (for example a suspected-fraud decline, or a request that cannot succeed on resubmission)."}}},"PluginError":{"type":"object","title":"Processing Failure","description":"A non-payment failure raised while processing the order.","properties":{"name":{"type":"string","description":"The plugin that raised the failure."},"message":{"type":"string","description":"The failure message."},"category":{"type":"string","description":"Coarse category of the failure."},"retry":{"type":"string","enum":["none"],"description":"What the caller should do next. Non-payment processing failures are not retryable."},"critical":{"type":"boolean","description":"Whether this failure was critical to the order."}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"502Response":{"description":"Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/admin/order":{"post":{"operationId":"sendAdminOrder","summary":"Submit Order","tags":["Orders"],"description":"Submit an order. `order_type` selects what the order does, and the rest of the body is the payload of that type. This one endpoint therefore covers most of what happens to a subscription after it starts.\n\nBuy a new subscription with `new`. Cancel one with `cancel_subscription`, and refund it with `refund`. Change what the customer has with `change_offer`, `add_offer` or `update_subscription`. Change their details with `change_address` or `update_customer_details`. Change how they pay with `change_payment`, `change_default_payment` or `delete_payment_method`. Record an answer they gave with `data_capture`.\n\nSend the same body to `/order/preview` first to see the totals, the taxes and the schedule that the order would produce, without submitting it.\n\nIf the order is created but immediate processing fails, the response keeps HTTP 200 and adds `error_reason` plus either a `payment` or `processing` section describing what went wrong and whether it is worth retrying.\n\nOptionally include a partner organisation to attribute the order to, run partner-specific eligibility checks, and associate the order and all its related objects with the partner organisation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdminOrderExtension"},{"discriminator":{"propertyName":"order_type","mapping":{"new":"#/components/schemas/CreateSubscription","change_offer":"#/components/schemas/ChangeOffer","add_offer":"#/components/schemas/AddOffer","cancel_subscription":"#/components/schemas/CancelSubscription","refund":"#/components/schemas/Refund","change_address":"#/components/schemas/ChangeAddress","update_customer_details":"#/components/schemas/UpdateCustomerDetails","change_payment":"#/components/schemas/ChangePayment","change_default_payment":"#/components/schemas/ChangeDefaultZuoraPaymentMethod","delete_payment_method":"#/components/schemas/DeletePaymentMethod","update_subscription":"#/components/schemas/UpdateSubscription","data_capture":"#/components/schemas/DataCapture"}},"oneOf":[{"$ref":"#/components/schemas/CreateSubscription"},{"$ref":"#/components/schemas/CreateGiftSubscription"},{"$ref":"#/components/schemas/RedeemGiftSubscription"},{"$ref":"#/components/schemas/ChangeOffer"},{"$ref":"#/components/schemas/AddOffer"},{"$ref":"#/components/schemas/CancelSubscription"},{"$ref":"#/components/schemas/Refund"},{"$ref":"#/components/schemas/UpdateSubscription"},{"$ref":"#/components/schemas/ChangeAddress"},{"$ref":"#/components/schemas/UpdateCustomerDetails"},{"$ref":"#/components/schemas/ChangePayment"},{"$ref":"#/components/schemas/ChangeDefaultZuoraPaymentMethod"},{"$ref":"#/components/schemas/DeletePaymentMethod"},{"$ref":"#/components/schemas/DataCapture"}]}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminOrderResponse"}}}},"400":{"description":"Invalid partner organisation"},"401":{"$ref":"#/components/responses/401ApplicationResponse"},"404":{"description":"Not found"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Preview Order

> Answers what an order would cost and change, without submitting it. Send the same body as \`POST /admin/order\` and read back the totals, the tax, the credit or refund amount, the effective date and the schedule of future charges. Use it to quote a price, to show a customer what a change means before they confirm, or to check an order before you send it.\
> \
> It previews every order type that the order endpoint accepts: a new subscription, an offer change, a cancellation, a refund or credit memo, a gift refund and a subscription update.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Submit or preview orders to trigger Limio's order orchestration framework. Supports new subscriptions, offer changes, cancellations, address updates, payment method changes, and gift redemptions."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"http","scheme":"bearer","bearerFormat":"Session Token","description":"Session-scoped Bearer token for authenticated end-user operations. Used by the Limio SDK to retrieve user-specific data such as entitlements. Tokens are issued during the checkout or login flow."}},"schemas":{"ChangeOffer":{"type":"object","title":"Change Offer","description":"Change the offer that is attached to a subscription.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["change_offer"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"offer":{"$ref":"#/components/schemas/OfferPayload"},"effectiveDate":{"description":"The date on which the Offer change will be effective. If not provided, the change will be effective at the end of the current term.","type":"string","format":"date-time"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"billingDetails":{"$ref":"#/components/schemas/Address"},"deliveryDetails":{"$ref":"#/components/schemas/Address"}},"required":["order_type","forSubscription","offer"]}]},"Order":{"type":"object","description":"Common order properties shared across all order types. These fields can be included alongside the order-type-specific payload (e.g. CreateSubscription, ChangeOffer).","properties":{"external_id":{"description":"Your own external order reference. Useful for correlating Limio orders with records in upstream systems.","type":"string"},"initiated_source":{"description":"Indicates where the order originated. Limio uses `shop` for storefront orders and `salesforce` for CRM-initiated orders. Custom values are supported for other integrations.","type":"string","enum":["shop","salesforce"]},"source":{"description":"The system that submitted the order. Limio uses `shop` for storefront submissions and `salesforce` for CRM submissions.","type":"string"},"process_immediately":{"description":"When `true`, the order is processed synchronously and the response includes the final processing result. When `false` (default), the order is queued for asynchronous processing.","type":"boolean","default":false}}},"SubscriptionByName":{"description":"Update subscription by name","properties":{"name":{"type":"string"}}},"SubscriptionById":{"description":"Update subscription by id","properties":{"id":{"type":"string"}}},"OfferPayload":{"description":"Reference to a published Limio offer.\nRetrieve `id` and `version` from `GET /offers/v2`.\n","required":["id","version"],"properties":{"id":{"type":"string","description":"The unique content hash of the offer. Retrieve from `GET /offers/v2`."},"version":{"type":"string","description":"The version hash of the offer. Use the latest version from the same API response."}}},"ZuoraPayment":{"type":"object","description":"Zuora Payment Method","properties":{"type":{"type":"string","enum":["zuora"]},"zuora":{"type":"object","properties":{"refId":{"type":"string","description":"The Zuora ID of the payment method to use for the payment"},"paymentGateway":{"type":"string","description":"The Zuora payment gateway to use for processing the payment"}}}}},"Address":{"description":"Address","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"workEmail":{"type":"string"},"phone":{"type":"string"},"workPhone":{"type":"string"},"otherPhone":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}},"AddOffer":{"type":"object","title":"Add Offer","description":"Replace the offer attached to a subscription with a discounted offer.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["add_offer"]},"forSubscription":{"description":"Subscription to update","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"offer":{"$ref":"#/components/schemas/OfferPayload"},"effectiveDate":{"description":"The date on which the Offer change will be effective. If not provided, the change will be effective at the end of the current term.","type":"string","format":"date-time"}},"required":["order_type","forSubscription","offer"]}]},"UpdateSubscription":{"type":"object","title":"Update Subscription","description":"Update an existing subscription — upgrade or downgrade the primary offer, add or remove add-ons, or change quantities on existing items.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["update_subscription"]},"owner":{"type":"string","description":"The identity ID of the subscription owner."},"forSubscription":{"description":"The subscription to update. Must include `id` and/or `name`.","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"forSubscriptionOffer":{"description":"The subscription offer being changed. Used by the checkout flow to resolve the current active offer when multiple offers exist on the subscription. Optional when the subscription has only one active offer.","type":"object","properties":{"offerId":{"type":"string","description":"The ID of the subscription_offer object."}}},"orderItems":{"type":"array","description":"The list of changes to apply. Each item specifies an action (add, remove, or update) targeting an offer, add-on, or existing subscription item.","items":{"$ref":"#/components/schemas/UpdateSubscriptionOrderItem"}},"effectiveDate":{"type":"string","format":"date-time","description":"ISO 8601 date when the changes take effect. If omitted, the system calculates it automatically based on the direction of change — upgrades and additions are effective immediately, downgrades and removals are effective at the end of the current term."}},"required":["order_type","forSubscription","orderItems"]}]},"UpdateSubscriptionOrderItem":{"description":"A single action within an update_subscription order. Each item adds, removes, or updates an offer or add-on on the subscription.","type":"object","required":["id","orderItemActionType","offer"],"properties":{"id":{"type":"string","description":"Unique identifier for this order item (typically a UUID)."},"orderItemActionType":{"type":"string","enum":["add","remove","update"],"description":"The action to perform.\n- `add` — Add a new offer or add-on to the subscription.\n- `remove` — Remove an existing subscription offer or add-on.\n- `update` — Change the quantity of an existing subscription item."},"type":{"type":"string","enum":["offer","add_on","subscription_offer","subscription_add_on"],"description":"The record type of the target item.\n- `offer` / `add_on` — Used with `add` actions. References a catalog offer or add-on.\n- `subscription_offer` / `subscription_add_on` — Used with `remove` and `update` actions. References an existing item on the subscription."},"offer":{"type":"object","description":"Reference to the catalog item (for add) or subscription item (for remove/update).","required":["id","version"],"properties":{"id":{"type":"string","description":"For `add` actions: the catalog offer or add-on ID. For `remove`/`update` actions: the subscription_offer or subscription_add_on ID."},"version":{"type":"string","description":"The version of the referenced object."}}},"quantity":{"type":"integer","minimum":1,"description":"The target quantity. Only applicable for `update` actions on items that support quantity changes (offers with `allow_multibuy` or `recurringVolume` pricing). Must be a positive integer within the offer's configured bounds."}}},"CancelSubscription":{"type":"object","title":"Cancel Subscription","description":"Cancel a subscription.","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["cancel_subscription"]},"forSubscription":{"description":"Subscription to cancel","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"effectiveDate":{"description":"The date on which the cancellation will be effective. If not provided, the cancellation will be effective at the end of the current term.","type":"string","format":"date-time"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"data":{"$ref":"#/components/schemas/CancelData"}},"required":["order_type","forSubscription"]}]},"CancelData":{"type":"object","description":"Cancel reasons data","properties":{"reason":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for the cancellation reason"}},"required":["id"]}}},"GiftRefund":{"type":"object","title":"Gift Refund","description":"Process a refund for a gift subscription","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["gift_refund"]},"subscriptionId":{"type":"string","description":"ID of the gift subscription to refund"},"data":{"type":"object","properties":{"gift_code":{"type":"string","description":"The gift code associated with the subscription"}}}},"required":["order_type","subscriptionId"]}]},"CreditMemo":{"type":"object","title":"Credit Memo","description":"Create a credit memo for a subscription to apply credits or adjustments","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["credit_memo"]},"forSubscription":{"description":"Subscription to apply the credit memo to","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"orderItems":{"type":"array","description":"Items to include in the credit memo","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"},"type":{"type":"string"}}}},"creditMemoReasonCode":{"type":"string","description":"Reason code for the credit memo"}},"required":["order_type","forSubscription","orderItems","creditMemoReasonCode"]}]},"CreateSubscription":{"type":"object","title":"Create Subscription","description":"Create a new subscription","allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"order_type":{"type":"string","enum":["new"]},"orderItems":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"}}}},"orderDiscount":{"$ref":"#/components/schemas/OrderDiscount"},"billingDetails":{"$ref":"#/components/schemas/Address"},"deliveryDetails":{"$ref":"#/components/schemas/Address"},"customerDetails":{"$ref":"#/components/schemas/CustomerDetails"},"tracking":{"$ref":"#/components/schemas/Tracking"},"payment":{"description":"Payment","oneOf":[{"$ref":"#/components/schemas/ZuoraPayment"}]},"orderDate":{"type":"string","format":"date-time","description":"the date on which the subscription should start"},"checkoutId":{"type":"string","description":"the limio session checkout id for this order"},"country":{"type":"string","description":"the country code of the customer's purchase location"}},"required":["order_type","billingDetails","customerDetails","orderItems","payment","country","checkoutId"]}]},"OrderDiscount":{"description":"Order Discount","type":"object","properties":{"name":{"type":"string","description":"The name of the order discount"},"productDetails":{"type":"object","properties":{"ratePlan":{"type":"object","properties":{"path":{"type":"string","description":"The path of the rate plan"}}},"product":{"type":"object","properties":{"path":{"type":"string","description":"The path of the product"}}}}},"product":{"$ref":"#/components/schemas/ProductDetails"},"discountOverrides":{"type":"object","properties":{"discountType":{"type":"string","description":"The type of the discount"},"durationLength":{"type":"number","description":"The period of time the discount is applied"},"durationType":{"type":"string","description":"The type of period of time the discount is applied"},"percentageDiscount":{"type":"number","description":"The percentage of the discount"},"amountDiscount":{"type":"number","description":"The amount of the discount"},"currency":{"type":"string","description":"The currency of the discount"},"orderItemsWithSpecifiedDiscount":{"type":"object","properties":{"discountedOffers":{"type":"array"}}}}}}},"ProductDetails":{"type":"object","properties":{"baseTemplate":{"type":"string"},"entitlements":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}},"path":{"type":"string"},"created":{"type":"string","format":"date-time"},"modified":{"type":"string","format":"date-time"},"attributes":{"$ref":"#/components/schemas/ProductAttributes"},"record_type":{"type":"string"},"lastSynced":{"type":"string","format":"date-time"},"synced":{"type":"boolean"},"syncedFrom":{"type":"string"}}},"Entitlement":{"type":"object","properties":{"$ref":{"type":"string"}}},"ProductAttributes":{"type":"object","properties":{"display_name__limio":{"type":"string"},"has_delivery__limio":{"type":"boolean"},"product_code__limio":{"type":"string"}}},"CustomerDetails":{"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}},"Tracking":{"type":"object","description":"Tracking data associated with the order, used for attribution and integration with external systems. When the basket resolves an owner, the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows. An owner is resolved from `accountId` or `zuoraAccountNumber` here, or from a renewal `subscriptionId` on the order itself.","properties":{"offers":{"type":"array","items":{"type":"string"}},"purchaseCountryCode":{"type":"string"},"accountId":{"type":"string","description":"Salesforce Account ID. When provided, Limio resolves or creates an identity owner for the basket and returns an `assistedCheckoutLink` in the response."},"zuoraAccountNumber":{"type":"string","description":"Zuora account number. Like `accountId`, resolves an identity owner for the basket, so the response includes an `assistedCheckoutLink`. `accountId` takes precedence when both are provided."},"contactId":{"type":"string","description":"Salesforce Contact ID associated with this order."},"userId":{"type":"string","description":"Salesforce User ID associated with this order."}}},"SwitchPreviewResponse":{"type":"object","description":"Preview response returned by the order preview endpoint. Contains the raw billing provider result and a normalised payment schedule that front-end consumers use to display pricing summaries.","properties":{"preview":{"type":"object","properties":{"success":{"type":"boolean"},"orderNumber":{"type":"string"},"orderId":{"type":"string"},"accountNumber":{"type":"string"},"status":{"type":"string"},"subscriptions":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"subscriptionId":{"type":"string"},"subscriptionNumber":{"type":"string"}}}},"paymentNumber":{"type":"string"},"paymentId":{"type":"string"},"paidAmount":{"type":"string"},"previewResult":{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"amountWithoutTax":{"type":"number"},"targetDate":{"type":"string","format":"date-time"},"taxAmount":{"type":"number"},"invoiceItems":{"type":"array","$ref":"#/components/schemas/ZuoraLineItem"}}}},"creditMemos":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"amountWithoutTax":{"type":"number"},"targetDate":{"type":"string","format":"date-time"},"taxAmount":{"type":"number"},"creditMemoItems":{"type":"array","items":{"$ref":"#/components/schemas/ZuoraLineItem"}}}}}}}}},"schedule":{"type":"array","description":"Normalised payment schedule derived from the billing provider preview. For `update_subscription` orders, the first schedule entry is filtered to show only charges related to the update (new charges, proration credits, and quantity amendment pairs). Subsequent entries show all charges since the customer pays the full amount on renewal. Entries before the order's effective date are excluded.","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Invoice date (ISO datetime without offset)."},"schedule_date":{"type":"string","format":"date-time","description":"Same as `date`. Included for backwards compatibility."},"type":{"type":"string","description":"Schedule entry type."},"amount":{"type":"string","description":"Total amount including tax."},"taxAmount":{"type":"number","description":"Tax portion of the total amount."},"amountWithoutTax":{"type":"string","description":"Subtotal excluding tax."},"currency":{"type":"string","description":"ISO 4217 currency code from the subscription."},"unit_amount":{"type":"string","description":"Total amount (same as `amount`)."},"quantity":{"type":"number"},"hasDiscount":{"type":"boolean","description":"Whether any charge in this schedule entry has `processingType: \"Discount\"`."},"amountExcludingDiscount":{"type":"string","description":"Subtotal of non-discount charges only (excludes tax). Same as `amountWithoutTax` when no discounts are present."},"discountUnitValue":{"type":"string","description":"Sum of `unitPrice` values from discount charges. `\"0.00\"` when no discounts are present."},"lineItems":{"type":"array","description":"Breakdown of individual charges within this schedule entry.","items":{"type":"object","properties":{"amountWithoutTax":{"type":"string","description":"Charge amount excluding tax."},"taxAmount":{"type":"string","description":"Tax amount for this charge."},"limioCatalogObjectId":{"type":"string","description":"Maps back to the Limio catalog record. Set via the `chargeDescription` field in Zuora charge overrides, formatted as `{record_type}-{id}`."},"processingType":{"type":"string","description":"Zuora processing type.","enum":["Charge","Discount"]},"chargeName":{"type":"string","description":"Name of the charge from the billing provider."},"productName":{"type":"string","description":"Name of the product from the billing provider."},"quantity":{"type":"number","description":"Quantity for this charge."}}}},"taxSummary":{"type":"array","description":"Tax amounts aggregated by tax code.","items":{"type":"object","properties":{"taxCode":{"type":"string","description":"Tax code identifier."},"taxRate":{"type":"number","description":"Tax rate as a decimal (e.g. 0.2 for 20%)."},"taxAmount":{"type":"number","description":"Total tax amount for this tax code."}}}},"reference":{"type":"string"}}}}}},"ZuoraLineItem":{"type":"object","properties":{"additionalInfo":{"type":"object","properties":{"quantity":{"type":"number"},"unitOfMeasure":{"type":"string"}}},"amountWithoutTax":{"type":"number"},"chargeDescription":{"type":"string"},"chargeName":{"type":"string"},"chargeNumber":{"type":"string"},"processingType":{"type":"string"},"productName":{"type":"string"},"productRatePlanChargeId":{"type":"string"},"serviceEndDate":{"type":"string","format":"date-time"},"serviceStartDate":{"type":"string","format":"date-time"},"subscriptionNumber":{"type":"string"},"taxAmount":{"type":"number"},"unitPrice":{"type":"number"}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"502Response":{"description":"Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/order/preview":{"post":{"operationId":"previewOrder","summary":"Preview Order","description":"Answers what an order would cost and change, without submitting it. Send the same body as `POST /admin/order` and read back the totals, the tax, the credit or refund amount, the effective date and the schedule of future charges. Use it to quote a price, to show a customer what a change means before they confirm, or to check an order before you send it.\n\nIt previews every order type that the order endpoint accepts: a new subscription, an offer change, a cancellation, a refund or credit memo, a gift refund and a subscription update.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"discriminator":{"propertyName":"order_type","mapping":{"change_offer":"#/components/schemas/ChangeOffer","add_offer":"#/components/schemas/AddOffer","update_subscription":"#/components/schemas/UpdateSubscription","cancel_subscription":"#/components/schemas/CancelSubscription","gift_refund":"#/components/schemas/GiftRefund","credit_memo":"#/components/schemas/CreditMemo","new":"#/components/schemas/CreateSubscription"}},"oneOf":[{"$ref":"#/components/schemas/ChangeOffer"},{"$ref":"#/components/schemas/AddOffer"},{"$ref":"#/components/schemas/UpdateSubscription"},{"$ref":"#/components/schemas/CancelSubscription"},{"$ref":"#/components/schemas/GiftRefund"},{"$ref":"#/components/schemas/CreditMemo"},{"$ref":"#/components/schemas/CreateSubscription"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchPreviewResponse"}}}},"401":{"$ref":"#/components/responses/401ApplicationResponse"},"404":{"description":"Not found"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Validate Gift Code

> Check a gift code before you redeem it. Limio makes sure that the code exists, is not redeemed, and is not expired.\
> \
> A valid code returns the items that the purchaser paid for, with every price set to zero, plus the recipient details from the gift purchase. Use these values to build the redemption order that you send to Submit Order.\
> \
> An invalid code also returns HTTP 200. Read \`success\` and \`error.code\` to find the reason. This call does not redeem the code, so you can repeat it.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Submit or preview orders to trigger Limio's order orchestration framework. Supports new subscriptions, offer changes, cancellations, address updates, payment method changes, and gift redemptions."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"OfferPayload":{"description":"Reference to a published Limio offer.\nRetrieve `id` and `version` from `GET /offers/v2`.\n","required":["id","version"],"properties":{"id":{"type":"string","description":"The unique content hash of the offer. Retrieve from `GET /offers/v2`."},"version":{"type":"string","description":"The version hash of the offer. Use the latest version from the same API response."}}},"RecipientDetails":{"type":"object","properties":{"startNow":{"type":"boolean","description":"if true, the gift subscription will begin on the date of the order, not when the gift is redeemed by the recipient"},"startDate":{"type":"string","format":"date-time","description":"send the gift on a specific date, will default to the order date if undefined"},"firstName":{"type":"string"},"lastName":{"type":"string"},"sendEmail":{"type":"boolean","description":"a flag that the order keeps for your email system. Limio does not send the gift email"},"message":{"type":"string","description":"a message from the purchaser to the recipient"},"email":{"type":"string","format":"email"}},"required":["email"]},"Address":{"description":"Address","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"workEmail":{"type":"string"},"phone":{"type":"string"},"workPhone":{"type":"string"},"otherPhone":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}},"Tracking":{"type":"object","description":"Tracking data associated with the order, used for attribution and integration with external systems. When the basket resolves an owner, the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows. An owner is resolved from `accountId` or `zuoraAccountNumber` here, or from a renewal `subscriptionId` on the order itself.","properties":{"offers":{"type":"array","items":{"type":"string"}},"purchaseCountryCode":{"type":"string"},"accountId":{"type":"string","description":"Salesforce Account ID. When provided, Limio resolves or creates an identity owner for the basket and returns an `assistedCheckoutLink` in the response."},"zuoraAccountNumber":{"type":"string","description":"Zuora account number. Like `accountId`, resolves an identity owner for the basket, so the response includes an `assistedCheckoutLink`. `accountId` takes precedence when both are provided."},"contactId":{"type":"string","description":"Salesforce Contact ID associated with this order."},"userId":{"type":"string","description":"Salesforce User ID associated with this order."}}}},"responses":{"401Response":{"description":"Unauthorized: the request lacks valid authentication credentials. This response is returned by the API gateway before the request reaches the application. Verify your Bearer token is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/validate/gift/{id}":{"post":{"operationId":"validateGiftCode","summary":"Validate Gift Code","tags":["Orders"],"description":"Check a gift code before you redeem it. Limio makes sure that the code exists, is not redeemed, and is not expired.\n\nA valid code returns the items that the purchaser paid for, with every price set to zero, plus the recipient details from the gift purchase. Use these values to build the redemption order that you send to Submit Order.\n\nAn invalid code also returns HTTP 200. Read `success` and `error.code` to find the reason. This call does not redeem the code, so you can repeat it.","parameters":[{"in":"path","name":"id","required":true,"description":"The gift code. A code that Limio generates has 11 letters and digits. The code is case-sensitive.","schema":{"type":"string","maxLength":64}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string","description":"The ID of a subscription that the recipient already has. When you supply it, the response adds an `order_type`: `credit` when that subscription renews automatically, `renew` when it does not. With `credit`, the items keep their prices so that you know the value of the gift."}}}}}},"responses":{"200":{"description":"The result of the check. A valid code returns the gift details. An invalid code returns `success: false` and an `error`.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Valid gift code","required":["giftCode","orderItems"],"properties":{"giftCode":{"type":"string"},"orderItems":{"type":"array","description":"The items from the gift purchase. Each `offer` has its `price__limio` values set to `\"0\"`.","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"}}}},"order_type":{"type":"string","description":"Present only when the request has a `subscriptionId`.","enum":["credit","renew"]},"country":{"type":"string","description":"The country code of the gift purchase."},"recipientDetails":{"$ref":"#/components/schemas/RecipientDetails"},"deliveryDetails":{"$ref":"#/components/schemas/Address"},"tracking":{"$ref":"#/components/schemas/Tracking"},"total":{"type":"object","description":"The amount that the purchaser paid.","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"path":{"type":"string","description":"The catalog path of the page of the gift purchase."},"campaignUrl":{"type":"string","description":"The URL of the page of the gift purchase."}}},{"type":"object","title":"Invalid gift code","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"`LI-GC-101`: the code does not exist. `LI-GC-102`: the code is redeemed or refunded. `LI-GC-103`: the code is expired.","enum":["LI-GC-101","LI-GC-102","LI-GC-103"]},"text":{"type":"string"}}}}}]}}}},"401":{"$ref":"#/components/responses/401Response"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/api/orders-api/orders.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.