API Documentation | Limio
Limio Commerce API (1.0.0)
Download OpenAPI specification: Download
E-mail: [email protected] URL: https://limio.zendesk.com/hc/en-gb/requests/new
A collection of APIs designed for interacting with Limio services.
Send Orders
APIs related to sending Limio Orders
Submit Order (POST /order)
Submit an order directly to Limio. This will apply the changes immediately and can be used to update a subscription, change the offer, or update customer details.
Security: bearerAuth
Request body (application/json, required) One of the following request types:
Create Subscription
Create Gift Subscription
Redeem Gift Subscription
Update Customer Details
Change Address
Change Offer
Update Subscription
Change Default Zuora Payment Method
Delete Payment Method
Add Offer
Cancel Subscription
Create a new subscription - example schema fields:
external_id (string) — external order reference
initiated_source (string) — initiated source of the order ("shop" or "salesforce")
source (string)
process_immediately (boolean) — if true the order is processed synchronously
order_type (string, required) — e.g. "new"
orderItems (array, required) — array of objects:
offer (object: OfferPayload) — published Limio Offer details (id, version)
quantity (number)
orderDiscount (object: OrderDiscount)
name (string)
productDetails (object)
ratePlan (object)
product (object)
product (object: ProductDetails)
baseTemplate, entitlements, path, created, modified, attributes, record_type, lastSynced, synced, syncedFrom
discountOverrides
discountType, durationLength, durationType, percentageDiscount, amountDiscount, currency, orderItemsWithSpecifiedDiscount
billingDetails (object: Address) — firstName, lastName, email, phone, company, address1, address2, city, state, postalCode, country
deliveryDetails (object: Address)
customerDetails (object: CustomerDetails) — firstName, lastName, phone, email
tracking (object: Tracking) — offers (array of strings), purchaseCountryCode, accountId, contactId, userId
payment (ZuoraPayment object, required)
type: "zuora"
zuora:
refId (string) — Zuora payment method id
paymentGateway (string)
orderDate (string, date-time) — subscription start date
checkoutId (string, required) — limio session checkout id
country (string, required) — customer purchase country code
Responses:
200 OK
401 Unauthorized
404 Not found
502 Bad Gateway
Example payload (application/json):
Example response (200):
Preview Order (POST /order/preview)
Preview an order in Limio to see the changes that will be applied. Useful to show the user expected charges, effective dates, and other details before confirming.
Security: bearerAuth
Request body (application/json, required)
Fields include (representative):
external_id, initiated_source, source, process_immediately
order_type (string, required) — e.g. add_offer, update_subscription, change_offer
forSubscription (SubscriptionByName or SubscriptionById) — subscription to update
offer (OfferPayload, required)
effectiveDate (date-time)
payment (ZuoraPayment)
billingDetails, deliveryDetails
Responses:
200 OK
401 Unauthorized
404 Not found
502 Bad Gateway
Example request:
Example response (200):
Large preview object containing:
preview: { success, orderNumber, orderId, accountNumber, status, subscriptions, paymentNumber, paidAmount, previewResult (invoices, creditMemos) }
schedule: array of scheduled charges
(See actual API response samples for full JSON structure.)
Subscription
APIs related to Limio Subscriptions
Get subscriptions by Salesforce ID (GET /objects/salesforce/identities/{id}/subscriptions)
Use to list subscriptions attached to a specified Salesforce ID.
Security: bearerAuth
Path parameters:
id (string, required): Salesforce Identity
Query parameters:
queryMore (string): pagination token
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Response contains a "subscriptions" array with detailed subscription, offer, product, tracking, customer, price and other information.
Get Subscription Timeline (GET /timeline/{path_type}/{id})
Retrieves timeline data for a subscription or customer by ID. Aggregates events, payment methods, addresses, offers, and schedules into a chronological history.
Security: bearerAuth
Path parameters:
path_type (string, required): "subscriptions" or "customers"
id (string, required): subscription or customer id
Responses:
200 Successfully retrieved timeline data
400 Bad request - Invalid parameters
401 Unauthorized
404 Subscription or customer not found
502 Bad Gateway
Example curl:
Response includes "subscriptions" (array of timeline events) and metadata.
Identities
APIs related to Limio Identities
Transfer Limio owner (POST /objects/owner_change)
Transfer ownership of all objects from one owner to another. Both source and destination owners must use the "@limio/id" format. This action only changes ownership of objects; it does not transfer or change the source owner's ID.
Security: bearerAuth
Request body (application/json, required):
sourceId (string)
destinationId (string)
message (string)
Responses:
200 All objects successfully transferred
401 Unauthorized
502 Bad Gateway
Example:
Example response:
Add external identity (Admin) (POST /objects/externalidentity/{owner})
Add an external identity to a Limio identity on behalf of an organization (admin-only). Requires OAuth bearer tokens.
Security: bearerAuth
Path parameters:
owner (string, required): Limio owner id (e.g. id-23252f4950f5efe7de30de37da283149)
Request body (application/json, required):
id_token (object)
iss (string)
sub (string)
Responses:
200 External identity successfully linked
401 Unauthorized
502 Bad Gateway
Example request:
Example response:
Remove external identity (Admin) (DELETE /objects/externalidentity/{owner})
Remove an external identity from a Limio identity (admin-only).
Security: bearerAuth
Path parameters:
owner (string, required)
Request body (application/json, required):
id_token (object)
iss (string)
sub (string)
Responses:
200 External identity successfully removed
401 Unauthorized
502 Bad Gateway
Example request:
Example response: { }
Forget Customer Data (POST /customer/{id}/forget_customer)
Obfuscate personal customer data for a specific customer id (irreversible).
Security: bearerAuth
Path parameters:
id (string, required): customer id (e.g. cus-fc689f05...)
Responses:
200 Data successfully scrubbed
401 Unauthorized
502 Bad Gateway
Example curl:
Example response:
Basket
APIs related to retrieving Limio Baskets
Get Abandoned Baskets (GET /checkout/abandoned)
Retrieve a list of abandoned baskets and filter by creation date.
Security: bearerAuth
Query parameters:
limit (number, required) — number of objects to return
createdAfter (date-time, required) — filter items created after provided ISO date-time
queryMore (string) — pagination token
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Response contains "items" array with baskets (id, created, customerDetails, orderItems, tracking, identities, completed false, recoveryLink, etc.).
Create or update a checkout session (POST /checkout/initiate)
Create or update a basket for tracking and later order submission. Returns basket ID.
Security: bearerAuth
Request body (application/json, required):
order (object, required)
orderItems (array, required) — offer payloads+quantity
external_id (string, required) — becomes checkoutId
tracking (object)
offers (array)
purchaseCountryCode
accountId, contactId, userId
country (string, required) — purchase country code
source (string, required)
order_type (string, required) — Enum: "new", "renew"
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example request:
Example response:
Session
APIs related to User Sessions
Get User Entitlements (GET /session/entitlements)
Get entitlements of a user session.
Security: sessionAuth
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Example response:
Get Objects
APIs to retrieve Limio objects (subscriptions, customers, orders, identities, addresses, schedules, payment methods, subscription offers, entitlements, events, process events, etc.)
Security: bearerAuth
Get Object (GET /objects/{service}/{path_type}/{id})
Path parameters:
service (string, required): "limio" (default), "zuora", "salesforce"
path_type (string, required): e.g. "orders", "customers", "subscriptions", "identities", "address", "schedules", "payment_methods", "subscription_offers", "user_entitlements", "gift_code", "promo_codes_v2", "events", "process"
id (string, required)
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Response: full object JSON (subscription, customer, order, etc.). See response samples for structures.
Get Objects (GET /objects/{service}/{path_type})
Retrieve a list of objects of a specific type.
Query parameters:
limit (number)
queryMore (string)
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Response: "items" array with summary objects and "queryMore" token.
Get Object Relationships (GET /objects/{service}/{path_type}/{id}/related)
Get objects related to a specific object.
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Response: "items" array of related objects.
Get Object Relationships By Record Type (GET /objects/{service}/{path_type}/{id}/related/{record_type})
Same as above filtered by record_type.
Example curl:
Get Object Subtype (GET /objects/{service}/{path_type}/{id}/objects)
Retrieve children objects of a parent object.
Example curl:
Get Object Subtype By Record Type (GET /objects/{service}/{path_type}/{id}/objects/{subtype})
Retrieve specific children objects matching record_type.
Example curl:
Get Object Events (GET /objects/{service}/{path_type}/{id}/events)
Get events associated with a specific object.
Example curl:
Response: "items" array of event objects and "unpackedItems" with enriched data.
Create Objects
APIs related to creating Limio Objects
Create Promo Code Objects (POST /objects/limio/promo_codes_v2)
Create a new promo code object (only promo codes v2 supported).
Security: bearerAuth
Request body (application/json, required):
name (string, required)
id (string, required) — e.g. promo_code_v2-abc123
data (PromoCodeWholeBasket or PromoCodeSelectedItems)
applicationLevel (string, required), value: "wholeBasket"
promoCode (string, required)
status (boolean, required)
description (string)
promoStartDate (date)
promoExpiryDate (date)
productDetails (PromoCodeProductDetails)
product (object, required)
ratePlan (object, required)
usage (availableQuantity)
discount (Discount Type Percentage or Fixed Amount) — discountType "DiscountPercentage" with percentageDiscount, durationLength, durationType
Responses:
200 OK
400 Bad request
401 Unauthorized
404 Not found
Example request:
Example response:
Update Objects
APIs related to updating Limio Objects
Update Object (PUT /objects/{service}/{path_type}/{id})
Update objects (subscription, customer, order, identity, address, schedule, payment method, subscription offer, promo code, user entitlement).
Security: bearerAuth
Path parameters:
service (string)
path_type (string)
id (string)
Request body (application/json, required):
name (string)
data (object | PromoCodeWholeBasket | PromoCodeSelectedItems) — nested updates require full structure as appropriate
quantity (number)
Responses:
200 OK
400 Bad request
401 Unauthorized
404 Not found
Example request:
Example response:
Delete Object (DELETE /objects/{service}/{path_type}/{id})
Delete objects (currently only promo codes v2 supported).
Security: bearerAuth
Responses:
200 OK
401 Unauthorized
404 Not found
502 Bad Gateway
Example curl:
Example response:
Add Object Relationship (POST /objects/{service}/{path_type}/{id}/related/{record_type})
Add a related identity object to a specific object.
Security: bearerAuth
Path parameters:
service (string)
id (string)
path_type (string)
record_type (string, required) — default "identity" (only identity allowed)
Request body (application/json, required):
id (string) — identity id to link
service (string) — identity service: "limio", "zuora", "salesforce"
Example:
Response: null (200 OK)
Get Catalog Items
APIs related to retrieving Limio Catalog Items
Note: Many catalog endpoints accept query parameters such as path, tags, reducedData, opt.pageSize, opt.modifiedAfter, opt.all, opt.queryMoreFrom, opt.queryMoreAlias and attributes.<YOUR_ATTRIBUTE> keys.
Authentication: ApiKey or bearerAuth (depending on endpoint)
Get Campaigns (GET /campaigns)
Retrieve campaigns that match queries. Returns hits count, items array and queryMore.
Security: ApiKey
Example curl:
Response: hits, header, items (campaign objects), queryMore.
Get Pages (GET /pages)
Retrieve published pages matching query params.
Security: ApiKey
Example curl:
Response: items, hits, queryMore, commitId, buildId, indexName.
Get Offers (GET /offers)
Retrieves offers in the catalog (includes legacy /offers and standalone /offers2). To fetch only v2 standalone offers use /offers/v2.
Security: ApiKey or bearerAuth
Query params: path, tags, reducedData, opt.pageSize, opt.modifiedAfter, opt.all, opt.queryMoreFrom, opt.queryMoreAlias, attributes.<...>
Example curl:
Response: hits, items (offer objects), queryMore, commitId.
Get Offers V2 (GET /offers/v2)
Retrieve standalone offers v2 (recommended if you only want standalone offers). Can default to published offers if Published Offers API is enabled; use offersSource query param to control.
Security: bearerAuth
Query parameters:
offersSource (string): "catalog" or "published"
path, tags, reducedData, opt.pageSize, opt.modifiedAfter, opt.all, opt.queryMoreFrom, opt.queryMoreAlias, attributes.<...>
Example curl:
Response: hits, items (v2 offers), queryMore, commitId.
Get Add Ons (GET /add_ons)
Retrieve standalone add-ons in the catalog.
Security: bearerAuth
Query parameters include addOnsSource ("catalog" or "published") and others similar to offers.
Example curl:
Response: hits, items, queryMore, commitId.
Get Assets (GET /assets)
Retrieve assets in the catalog.
Security: ApiKey or bearerAuth
Example curl:
Response: hits, items (asset objects), queryMore.
Get Products (GET /products)
Retrieve products in the catalog.
Security: ApiKey or bearerAuth
Example curl:
Response: hits, items, queryMore, commitId.
Get Segments (GET /segments)
Retrieve catalog segments.
Security: ApiKey or bearerAuth
Example curl:
Response: hits, items, queryMore, commitId.
Get Journeys (GET /journeys)
Retrieve journeys in the catalog.
Security: ApiKey or bearerAuth
Example curl:
Response: starting_point, fallback_tag, journeys array.
Update Catalog Items
APIs related to updating Limio Catalog Items
Bulk Update (PUT /limio/catalogs/1/bulk-update)
Perform bulk update operations on catalog items.
Security: bearerAuth
Request body (application/json, required):
diffs (array of objects)
path (string) — offer path
diff (object) — attributes to change
Responses:
200 OK
401 Unauthorized
404 Not found
Example:
Example response:
Build
APIs related to building Limio Campaigns and pages
Build Campaigns and Pages (POST /shop/builds)
Build campaigns and pages in bulk.
Security: bearerAuth
Request body (application/json, required):
items (array) — list of campaign and page paths to build (e.g. "/offers/Limio Campaign", "/pages/Limio Page")
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example:
Example response:
Repository Component Builds (GET /component/builds)
Fetch custom component builds.
Security: bearerAuth
Query params:
commitHash (string) — retrieve build info for this commit
Responses:
200 OK
401 Unauthorized
404 Builds not found
Example curl:
Example response:
Publish
APIs related to publishing Limio Campaigns and pages
Publish Campaigns and Pages (POST /publish)
Publish campaigns and pages (make them live).
Security: bearerAuth
Request body (application/json, required):
tags (array) — tags of campaigns/pages to publish
buildId (string)
name (string) — name of campaign/page to publish
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example:
Example response: success flag and publishedData pages structure.
Sync Zuora Data
APIs related to syncing Zuora Data
Sync Zuora Subscription (POST /plugins/zuora/sync/subscription/{id})
Update or create subscriptions/customers in Limio for orders created outside Limio (e.g., directly in Zuora).
Security: bearerAuth
Path parameters:
id (string, required) — Zuora subscription id
Responses:
200 OK
401 Unauthorized
502 Bad Gateway
Example curl:
Example response:
Journeys V2
APIs related to Limio Journeys V2
Security: ApiKey or bearerAuth (depending on endpoint)
Get Journeys V2 (GET /v2/journey)
Retrieve journeys v2.
Example curl:
Response: starting_point, fallback_tag, journeys array.
Add Journey V2 (POST /v2/journey)
Add a new journey.
Security: bearerAuth
Request body:
name (string)
Responses:
200 OK
401 Unauthorized
409 Conflict
Example:
Example response:
Get Journey V2 by name (GET /v2/journey/{journeyName})
Get a journey by name.
Security: bearerAuth
Path parameter:
journeyName (string, required)
Responses:
200 OK
401 Unauthorized
404 Journey not found
Example curl:
Response contains journey data, status, id, created/updated timestamps, version.
Delete Journey V2 by name (DELETE /v2/journey/{journeyName})
Delete a journey by name.
Security: bearerAuth
Responses:
200 Successfully deleted
401 Unauthorized
404 Journey not found
Example curl:
Example response:
Update or Create Journey V2 (PUT /v2/journey/{journeyName})
Update an existing Journey V2 by name, or create if it does not exist.
Security: bearerAuth
Path parameter:
journeyName (string) — name of journey to update
Request body (application/json, required):
name (string)
data (object)
journeys (array of objects)
id (uuid), conditions (array), actions (array)
starting_point (string)
fallback_tag (string)
domains (array of strings)
Responses:
200 OK
401 Unauthorized
Example request:
Example response: echoes back the journey structure.
If you want, I can:
Convert specific example request/response pairs into separate example blocks titled per language (curl / JavaScript / Python).
Split this document into separate GitBook pages (e.g., Orders, Subscriptions, Catalog) and add ready-to-use code snippets for common use cases. Which would you prefer?
Last updated
Was this helpful?