# Partner Orders

Partner endpoints for order submission and preview. Orders are attributed to the partner organisation and run partner-specific eligibility checks.

## Submit Partner Order

> Submit an order using partner credentials. The order is attributed to the partner organisation and runs partner-specific eligibility checks. All related objects are associated with the partner context.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Orders","description":"Partner endpoints for order submission and preview. Orders are attributed to the partner organisation and run partner-specific eligibility checks."}],"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":["partner"]}],"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":{"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"]}]},"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":{"/partner/order":{"post":{"operationId":"partnerSendOrder","summary":"Submit Partner Order","tags":["Partner Orders"],"description":"Submit an order using partner credentials. The order is attributed to the partner organisation and runs partner-specific eligibility checks. All related objects are associated with the partner context.","requestBody":{"required":true,"content":{"application/json":{"schema":{"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_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/ChangeDefaultZuoraPaymentMethod"},{"$ref":"#/components/schemas/DeletePaymentMethod"}]}}}},"responses":{"200":{"description":"Order submitted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid order payload."},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Not found."},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Preview Partner Order

> Preview an order within the partner context without submitting it. Returns the calculated pricing, line items, and billing schedule from the billing provider. Useful for showing the customer a price summary before confirming the order.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Orders","description":"Partner endpoints for order submission and preview. Orders are attributed to the partner organisation and run partner-specific eligibility checks."}],"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":["partner"]}],"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>`"}},"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":{"/partner/order/preview":{"post":{"operationId":"partnerPreviewOrder","summary":"Preview Partner Order","tags":["Partner Orders"],"description":"Preview an order within the partner context without submitting it. Returns the calculated pricing, line items, and billing schedule from the billing provider. Useful for showing the customer a price summary before confirming the order.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order payload to preview."}}}},"responses":{"200":{"description":"Order preview with calculated pricing.","content":{"application/json":{"schema":{"type":"object","description":"Preview result from the billing provider. Structure varies by billing plugin (Zuora, Stripe)."}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```