# 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. 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 `accountId` is provided, the basket is assigned an owner and the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows.","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."},"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","checkoutId","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":"send the recipient an email with the gift details, this includes the gift code"},"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","checkoutId","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"]}}},"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"]}]},"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":"Processing status of the order.","enum":["complete","pending","failed"]},"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."}}}},"responses":{"401Response":{"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":{"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. 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.","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","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"}},"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/UpdateSubscription"},{"$ref":"#/components/schemas/ChangeAddress"},{"$ref":"#/components/schemas/UpdateCustomerDetails"},{"$ref":"#/components/schemas/ChangePayment"},{"$ref":"#/components/schemas/ChangeDefaultZuoraPaymentMethod"},{"$ref":"#/components/schemas/DeletePaymentMethod"}]}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid partner organisation"},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Not found"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Preview Order

> Preview an order in Limio to see the changes that will be applied. This can be used to show the user what will happen before they confirm the order, including changes to future charges, the effective date of the change, and any other details. Supports previewing new subscriptions, offer changes, cancellations, credit memos, gift refunds, and subscription updates.

```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":["checkout"]}],"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":{"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 `accountId` is provided, the basket is assigned an owner and the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows.","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."},"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":{"401Response":{"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":{"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":"Preview an order in Limio to see the changes that will be applied. This can be used to show the user what will happen before they confirm the order, including changes to future charges, the effective date of the change, and any other details. Supports previewing new subscriptions, offer changes, cancellations, credit memos, gift refunds, and subscription updates.","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/401Response"},"404":{"description":"Not found"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```