> 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/partner-portal-api/partner-subscriptions.md).
# Partner Subscriptions
Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context.
## Retrieve existing subscription update checkout basket (Partner)
> Partner endpoint to fetch existing basket by basketId from landing state cookie.\
> Used to retrieve current checkout state after page refresh or navigation.\
> \
> Requires partner authentication.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"schemas":{"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"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/checkout/subscription":{"get":{"operationId":"getPartnerSubscriptionCheckout","summary":"Retrieve existing subscription update checkout basket (Partner)","tags":["Partner Subscriptions"],"description":"Partner endpoint to fetch existing basket by basketId from landing state cookie.\nUsed to retrieve current checkout state after page refresh or navigation.\n\nRequires partner authentication.\n","parameters":[{"name":"Cookie","in":"header","required":true,"schema":{"type":"string"},"description":"Landing state cookie containing basketId"}],"responses":{"200":{"description":"Basket retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"No basket found in landing state","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Initiate subscription update checkout (Partner)
> Partner endpoint to create a new basket for subscription updates with available upgrade/downgrade options.\
> This is the first step in updating a subscription - it creates a basket and returns available actions.\
> \
> \*\*Returns:\*\*\
> \- Basket with available upgrades, downgrades, cross-sells, and add-ons\
> \- Sets landing state cookie with basketId for subsequent requests\
> \
> \*\*Status 423:\*\* Subscription has pending change (locked until date passes)\
> \
> Requires partner authentication.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"schemas":{"InitiateSubscriptionCheckoutRequest":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["forSubscription","order_type"],"properties":{"external_id":{"type":"string","maxLength":128,"pattern":"^[0-9a-zA-Z-_]+$","description":"External identifier for tracking purposes"},"checkoutId":{"type":"string","description":"Optional checkout identifier (usually auto-generated)"},"forSubscription":{"type":"object","description":"Target subscription for modification (id or name required)","properties":{"id":{"type":"string","description":"Subscription ID"},"name":{"type":"string","description":"Subscription reference"}},"anyOf":[{"required":["id"]},{"required":["name"]}]},"forSubscriptionOffer":{"type":"object","description":"Optional - Pre-select target offer for subscription modification","properties":{"offerId":{"type":"string","description":"Target offer ID to switch to"}}},"order_type":{"type":"string","enum":["update_subscription"],"description":"Must be \"update_subscription\" for subscription modifications"},"orderItems":{"type":"array","description":"Optional initial order items","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}}}},"tracking":{"type":"object","description":"Optional tracking data for analytics and reporting"}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"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/checkout/subscription":{"post":{"operationId":"initiatePartnerSubscriptionCheckout","summary":"Initiate subscription update checkout (Partner)","tags":["Partner Subscriptions"],"description":"Partner endpoint to create a new basket for subscription updates with available upgrade/downgrade options.\nThis is the first step in updating a subscription - it creates a basket and returns available actions.\n\n**Returns:**\n- Basket with available upgrades, downgrades, cross-sells, and add-ons\n- Sets landing state cookie with basketId for subsequent requests\n\n**Status 423:** Subscription has pending change (locked until date passes)\n\nRequires partner authentication.\n","parameters":[{"name":"xLimioRecaptcha","in":"header","required":true,"schema":{"type":"string"},"description":"reCAPTCHA token for bot prevention"},{"name":"xForwardedFor","in":"header","schema":{"type":"string"},"description":"Client IP address"},{"name":"referer","in":"header","schema":{"type":"string"},"description":"Referrer URL for journey tracking"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateSubscriptionCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout basket created successfully","headers":{"Set-Cookie":{"description":"Landing state cookie with basketId","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"400":{"description":"Invalid request body or missing required fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"423":{"description":"Subscription has pending change, checkout locked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Update subscription checkout basket (Partner)
> Partner endpoint to update existing basket with order items (add/remove offers and add-ons).\
> \
> \*\*Business Logic:\*\*\
> \- Only 1 add offer allowed per request\
> \- System auto-adds remove action for current subscription offer when adding new offer\
> \- System auto-removes incompatible add-ons when switching subscription offers\
> \- System calculates prices, line items, and effective dates\
> \- Cross-sells are recalculated based on updated basket\
> \
> \*\*Requirements:\*\*\
> \- basketId must be present in landing state cookie (from POST response)\
> \- Basket must be accessible by partner\
> \
> Requires partner authentication.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"schemas":{"UpdateSubscriptionCheckoutRequest":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["forSubscription","order_type"],"properties":{"external_id":{"type":"string","maxLength":128,"pattern":"^[0-9a-zA-Z-_]+$","description":"External identifier for tracking"},"checkoutId":{"type":"string","description":"Checkout identifier from basket"},"forSubscription":{"type":"object","description":"Target subscription reference","properties":{"id":{"type":"string","description":"Subscription ID"},"name":{"type":"string","description":"Subscription name"}}},"order_type":{"type":"string","enum":["update_subscription"],"description":"Must be \"update_subscription\""},"orderItems":{"type":"array","description":"Order items to add/remove (max 1 add offer at a time)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}}}},"tracking":{"type":"object","additionalProperties":true,"description":"Optional tracking data for analytics and reporting"}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"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/checkout/subscription":{"put":{"operationId":"updatePartnerSubscriptionCheckout","summary":"Update subscription checkout basket (Partner)","tags":["Partner Subscriptions"],"description":"Partner endpoint to update existing basket with order items (add/remove offers and add-ons).\n\n**Business Logic:**\n- Only 1 add offer allowed per request\n- System auto-adds remove action for current subscription offer when adding new offer\n- System auto-removes incompatible add-ons when switching subscription offers\n- System calculates prices, line items, and effective dates\n- Cross-sells are recalculated based on updated basket\n\n**Requirements:**\n- basketId must be present in landing state cookie (from POST response)\n- Basket must be accessible by partner\n\nRequires partner authentication.\n","parameters":[{"name":"xLimioRecaptcha","in":"header","required":true,"schema":{"type":"string"},"description":"reCAPTCHA token for bot prevention"},{"name":"Cookie","in":"header","required":true,"schema":{"type":"string"},"description":"Landing state cookie containing basketId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionCheckoutRequest"}}}},"responses":{"200":{"description":"Basket updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"400":{"description":"Invalid request or multiple add offers provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Basket not found in landing state","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Get Partner Self-Service Checkout
> Retrieve the current self-service checkout state for a partner-managed subscription update. Returns the basket with available actions.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"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/mma/checkout":{"get":{"operationId":"getPartnerSelfServiceCheckout","summary":"Get Partner Self-Service Checkout","tags":["Partner Subscriptions"],"description":"Retrieve the current self-service checkout state for a partner-managed subscription update. Returns the basket with available actions.","responses":{"200":{"description":"Self-service checkout state retrieved.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Initiate Partner Self-Service Checkout
> Create a self-service checkout session for updating a partner-managed subscription. Returns available upgrade, downgrade, and add-on options.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"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/mma/checkout":{"post":{"operationId":"initiatePartnerSelfServiceCheckout","summary":"Initiate Partner Self-Service Checkout","tags":["Partner Subscriptions"],"description":"Create a self-service checkout session for updating a partner-managed subscription. Returns available upgrade, downgrade, and add-on options.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Self-service checkout session created.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Update Partner Self-Service Checkout
> Update the self-service checkout basket for a partner-managed subscription. Add or remove offers and add-ons from the basket.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"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/mma/checkout":{"put":{"operationId":"updatePartnerSelfServiceCheckout","summary":"Update Partner Self-Service Checkout","tags":["Partner Subscriptions"],"description":"Update the self-service checkout basket for a partner-managed subscription. Add or remove offers and add-ons from the basket.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Self-service checkout updated.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## List Partner Subscriptions
> Retrieve subscriptions visible to the authenticated partner organisation. Can optionally filter by owner ID to list subscriptions for a specific customer within the partner context.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"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/mma/subscriptions":{"get":{"operationId":"getPartnerSubscriptions","summary":"List Partner Subscriptions","tags":["Partner Subscriptions"],"description":"Retrieve subscriptions visible to the authenticated partner organisation. Can optionally filter by owner ID to list subscriptions for a specific customer within the partner context.","parameters":[{"name":"ownerId","in":"query","required":false,"description":"Filter subscriptions by owner (customer) ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of subscriptions.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Subscription objects.","items":{"type":"object"}},"queryMore":{"type":"string","description":"Pagination token for the next page of results."}}}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
## Get Partner Subscription Detail
> Retrieve a single subscription with its related objects (schedule, offers, add-ons) within the partner organisation context. Verifies the partner has access to the requested subscription.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Partner Subscriptions","description":"Partner endpoints for subscription management — list subscriptions, view subscription details, manage self-service checkout flows, and handle subscription updates within the partner context."}],"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 `"}},"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/mma/subscriptions/{id}":{"get":{"operationId":"getPartnerSubscription","summary":"Get Partner Subscription Detail","tags":["Partner Subscriptions"],"description":"Retrieve a single subscription with its related objects (schedule, offers, add-ons) within the partner organisation context. Verifies the partner has access to the requested subscription.","parameters":[{"name":"id","in":"path","required":true,"description":"The subscription ID.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"Subscription detail with related objects.","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","description":"The subscription object with related data."},"schedule":{"type":"array","description":"The subscription's billing schedule.","items":{"type":"object"}},"offers":{"type":"array","description":"Offers associated with the subscription.","items":{"type":"object"}},"addOns":{"type":"array","description":"Add-ons associated with the subscription.","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/401Response"},"403":{"description":"Partner does not have access to this subscription."},"404":{"description":"Subscription not found."},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.limio.com/api/partner-portal-api/partner-subscriptions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.