# Subscriptions Retrieve subscriptions, query subscriptions by Salesforce identity, view subscription timelines, and create custom timeline events. ## Get subscriptions by Salesforce ID > This API can be used to see all of the subscriptions that are attached to a specified Salesforce ID. ```json {"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Retrieve subscriptions, query subscriptions by Salesforce identity, view subscription timelines, and create custom timeline events."}],"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":["MMA"]}],"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":{"Subscription":{"type":"object","description":"A Limio subscription object representing a customer's active or historical subscription.","properties":{"name":{"type":"string","description":"Human-readable subscription reference code."},"start":{"type":"string","format":"date","description":"The date the subscription started or is scheduled to start."},"data":{"$ref":"#/components/schemas/SubscriptionData"},"status":{"type":"string","description":"Current lifecycle status of the subscription.","enum":["active","cancelled","expired","pending"]},"record_type":{"type":"string","description":"Object type identifier. Always `subscription` for this schema."},"owner":{"type":"string","description":"The identity ID that owns this subscription, prefixed with `id-`."},"customer":{"type":"string","description":"The customer ID associated with this subscription, prefixed with `cus-`."},"id":{"type":"string","description":"Unique subscription identifier, prefixed with `sub-`."},"service":{"type":"string","description":"The service this subscription belongs to.","enum":["limio","zuora","salesforce"]},"ref":{"type":"string","description":"Internal reference linking the subscription to its originating order."},"created":{"type":"string","format":"date-time","description":"Timestamp when the subscription was created."},"updated":{"type":"string","format":"date-time","description":"Timestamp when the subscription was last modified."},"reference":{"type":"string","description":"External reference code, typically matches the `name` field."},"mode":{"type":"string","description":"Deployment mode of the subscription.","enum":["production","test"]}}},"SubscriptionData":{"type":"object","properties":{"name":{"type":"string"},"tracking":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"string"}},"purchaseCountryCode":{"type":"string"},"accountId":{"type":"string"},"contactId":{"type":"string"},"userId":{"type":"string"}}},"offer":{"$ref":"#/components/schemas/Offer"},"quantity":{"type":"integer"},"termEndDate":{"type":"string","format":"date"},"price":{"$ref":"#/components/schemas/Price"},"termStartDate":{"type":"string","format":"date"},"attributes":{"type":"object","properties":{"gift":{"type":"boolean"},"external":{"type":"boolean"}}},"id":{"type":"string"},"purchaseCountry":{"type":"string"},"startDate":{"type":"string","format":"date"},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductDetails"}},"schedule":{"type":"array","items":{"$ref":"#/components/schemas/Schedule"}},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"address":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}}},"Offer":{"type":"object","description":"A Limio offer object representing a purchasable subscription offer with pricing, products, and configuration.","properties":{"mode":{"type":"string","description":"Deployment mode of the offer.","enum":["production","test"]},"path":{"type":"string","description":"Catalog path of the offer. V2 offers use `/offers2/...`, legacy offers use `/offers/...`."},"data":{"$ref":"#/components/schemas/OfferData"},"service":{"type":"string","description":"The service this offer belongs to."},"created":{"type":"string","format":"date-time","description":"Timestamp when the offer was created."},"name":{"type":"string","description":"Display name of the offer."},"id":{"type":"string","description":"Unique offer identifier (content-addressable hash)."},"type":{"type":"string","description":"Object type within the catalog hierarchy."},"updated":{"type":"string","format":"date-time","description":"Timestamp when the offer was last modified."},"version":{"type":"string","description":"Version hash of the offer. Changes when the offer content is updated. Used with the Published Offers API for versioned offer management."},"record_type":{"type":"string","description":"Object type identifier. Always `offer` for this schema."},"status":{"type":"string","description":"Publication status of the offer.","enum":["active","inactive"]}}},"OfferData":{"type":"object","properties":{"price__limio":{"type":"array","items":{}},"created":{"type":"string","format":"date-time"},"duplicatedFrom":{"type":"string"},"type":{"type":"string"},"version":{"type":"string"},"record_type":{"type":"string"},"productBundles":{"type":"array","items":{"type":"object","properties":{"revenue_split":{"type":"string"},"product_path":{"type":"string"},"rate_plan":{"type":"string"}}}},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductDetails"}},"baseTemplate":{"type":"string"},"path":{"type":"string"},"priceReference":{"type":"string"},"price":{"type":"array","items":{}},"name":{"type":"string"},"modified":{"type":"string","format":"date-time"},"attributes":{"type":"object","properties":{"checkout_description__limio":{"type":"string"},"price__limio":{"type":"array","items":{"type":"object","properties":{"delay_interval_type":{"type":"string"},"name":{"type":"string"},"delay_interval":{"type":"string"},"repeat_interval":{"type":"integer"},"attributes":{"type":"array","items":{}},"label":{"type":"string"},"trigger":{"type":"string"},"repeat_interval_type":{"type":"string"},"repeat_count":{"type":"integer"},"type":{"type":"string"},"value":{"type":"string"},"currencyCode":{"type":"string"}}}},"default_quantity_options__limio":{},"supportBillingFrequencyChange__zuora":{"type":"boolean"},"allowed_countries__limio":{"type":"array","items":{"type":"string"}},"label__limio":{"type":"array","items":{"type":"string"}},"term__limio":{"type":"object","properties":{"renewal_type":{"type":"string"},"renewal_trigger":{"type":"string"}}},"display_price__limio":{"type":"string"},"cta_text__limio":{"type":"string"},"payment_types__limio":{"type":"array","items":{"type":"string"}},"sales_channel__limio":{"type":"array","items":{"type":"string"}},"display_name__limio":{"type":"string"},"checkout__limio":{"type":"object","properties":{"checkout_type":{"type":"string"}}},"initial_term__limio":{"type":"object","properties":{"renewal_type":{"type":"string"},"length":{"type":"integer"},"renewal_trigger":{"type":"string"},"type":{"type":"string"}}},"push_to_checkout__limio":{"type":"boolean"},"autoRenew__limio":{"type":"boolean"},"offer_type__limio":{"type":"string"}}},"id":{"type":"string"},"user":{"type":"string"}}},"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"}}},"Price":{"type":"object","properties":{"summary":{"type":"object","properties":{"headline":{"type":"string"}}},"currency":{"type":"string"},"amount":{"type":"number"}}},"Schedule":{"type":"object","properties":{"data":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"amountWithoutTax":{"type":"string"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}}}}}},"LineItem":{"type":"object","properties":{"amountWithoutTax":{"type":"string"},"processingType":{"type":"string"},"quantity":{"type":"integer"},"taxAmount":{"type":"string"},"chargeName":{"type":"string"},"productName":{"type":"string"},"chargeDescription":{"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"}}},"Customer":{"type":"object","description":"A Limio customer object containing personal details and associated addresses.","properties":{"data":{"type":"object","description":"Core customer data fields.","properties":{"name":{"type":"string","description":"Full name of the customer."},"email":{"type":"string","description":"Customer email address."},"firstName":{"type":"string","description":"Customer first name."},"lastName":{"type":"string","description":"Customer last name."},"purchaseCountry":{"type":"string","description":"ISO country code of the customer's purchase country."},"trialist":{"type":"boolean","description":"Whether the customer is on a trial subscription."},"address":{"type":"array","description":"List of addresses associated with the customer.","items":{"$ref":"#/components/schemas/CustomerAddress"}}}},"status":{"type":"string","description":"Current customer status."},"record_type":{"type":"string","description":"Object type identifier. Always `customer` for this schema."},"owner":{"type":"string","description":"The identity ID that owns this customer record."},"id":{"type":"string","description":"Unique customer identifier, prefixed with `cus-`."},"service":{"type":"string","description":"The service this customer belongs to."},"created":{"type":"string","format":"date-time","description":"Timestamp when the customer record was created."},"updated":{"type":"string","format":"date-time","description":"Timestamp when the customer record was last modified."},"reference":{"type":"string","description":"External reference for the customer."},"mode":{"type":"string","description":"Deployment mode."}}},"CustomerAddress":{"type":"object","description":"Customer Address object","title":"Get Customer Address Response","properties":{"record_type":{"type":"string"},"id":{"type":"string"},"relationship_id":{"type":"string"},"data":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"country":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"address1":{"type":"string"},"postalCode":{"type":"string"},"company":{"type":"string"},"state":{"type":"string"},"email":{"type":"string","format":"email"}}},"related":{"type":"string"},"service":{"type":"string"},"start":{"type":"string","format":"date-time"},"relationship_type":{"type":"string"},"mode":{"type":"string"},"created":{"type":"string","format":"date-time"},"status":{"type":"string"},"owner":{"type":"string"},"customer":{"type":"string"},"updated":{"type":"string","format":"date-time"},"reference":{"type":"string"}}}},"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":{"/objects/salesforce/identities/{id}/subscriptions":{"get":{"operationId":"getIdentitySubscriptions","summary":"Get subscriptions by Salesforce ID","description":"This API can be used to see all of the subscriptions that are attached to a specified Salesforce ID.","tags":["Subscriptions"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The Salesforce Identity"},{"in":"query","name":"queryMore","description":"A hash returned from a call to the API that can be used to retrieve the next page of results.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"queryMore":{"type":"string","description":"Cursor for the next page of results"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}} ``` ## Add a Timeline Event > Currently supported for \*\*subscriptions\*\*. To create a custom Event and attach it to that specified Object’s Timeline.
```json {"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Retrieve subscriptions, query subscriptions by Salesforce identity, view subscription timelines, and create custom timeline events."}],"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":{"CreateTimelineEvent":{"type":"object","required":["forSubscription","name","type","fields"],"properties":{"forSubscription":{"description":"Subscription to add the event for","oneOf":[{"$ref":"#/components/schemas/SubscriptionByName"},{"$ref":"#/components/schemas/SubscriptionById"}]},"name":{"type":"string","description":"Event name"},"type":{"type":"string","description":"Domain/type of event"},"source":{"type":"string","description":"Source of the event e.g. system, user, webhook"},"fields":{"type":"array","description":"Renderable data for the Timeline. Each item is shown as a field row in the UI. Use `additionalInfo` for currency codes, date locale hints, masks, etc.\n","items":{"$ref":"#/components/schemas/TimelineField"}}}},"SubscriptionByName":{"description":"Update subscription by name","properties":{"name":{"type":"string"}}},"SubscriptionById":{"description":"Update subscription by id","properties":{"id":{"type":"string"}}},"TimelineField":{"type":"object","required":["label","type"],"properties":{"label":{"type":"string","description":"Field label to display in the Timeline UI"},"type":{"type":"string","description":"Type of field to render","enum":["string","date","currency","number","boolean","json"]},"value":{"description":"Field value as rendered by the Timeline. Null values hide the row.","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"additionalInfo":{"type":"string","description":"Optional metadata for formatting (e.g. currency code GBP, locale GB)"}}},"CreateTimelineEventResponse":{"type":"object","required":["id","status","reference"],"properties":{"id":{"type":"string","description":"Limio event ID generated for the created event"},"reference":{"type":"string","description":"Limio event reference generated for the created event"},"status":{"type":"string","description":"Processing status of the event"}}}},"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":{"/timeline/subscription":{"post":{"operationId":"addTimelineEvent","summary":"Add a Timeline Event","description":"Currently supported for **subscriptions**. To create a custom Event and attach it to that specified Object’s Timeline.\n","tags":["Subscriptions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimelineEvent"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimelineEventResponse"}}}},"400":{"description":"Bad request (missing or invalid fields)"},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Not found"},"502":{"$ref":"#/components/responses/502Response"}}}}}} ``` ## Get Subscription Timeline > Retrieves timeline data for a given subscription or customer by ID.\ > This API aggregates relevant events, payment methods, addresses, offers,\ > and schedules to create a chronological activity history.\ > \- For \`subscriptions\` path parameter: Returns timeline for that specific subscription\ > \- For \`customers\` path parameter: Returns timeline for all subscriptions owned by that customer
```json {"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Retrieve subscriptions, query subscriptions by Salesforce identity, view subscription timelines, and create custom timeline events."}],"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":{"GetTimelineResponse":{"type":"object","properties":{"metadata":{"type":"object","properties":{"ownerId":{"type":"string","description":"The owner ID of the subscription or customer"}},"required":["ownerId"]},"subscriptions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","description":"Human-readable action description (e.g., \"New Subscription\", \"Change Payment\")"},"type":{"type":"string","description":"The order type (e.g., \"order.new\", \"order.change_payment\")"},"subscriptionId":{"type":"string","description":"The unique identifier of the subscription"},"subscriptionNumber":{"type":"string","description":"The subscription number/name"},"created":{"type":"string","format":"date-time","description":"When the event was created"},"createdBy":{"type":"string","description":"User ID who created the event"},"status":{"type":"string","description":"Current status of the event (e.g. error, completed)"},"service":{"type":"string","description":"Service name (e.g., \"Zuora\")"},"fields":{"type":"array","description":"Additional fields specific to the event type, such as dates and prices","items":{"type":"object","additionalProperties":true}},"error":{"type":"boolean","description":"Indicates if there was an error processing this timeline event"}},"required":["action","type","subscriptionId","subscriptionNumber","created","createdBy","status"]}}},"required":["metadata","subscriptions"]}},"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":{"/timeline/{path_type}/{id}":{"get":{"operationId":"getTimeline","tags":["Subscriptions"],"summary":"Get Subscription Timeline","description":"Retrieves timeline data for a given subscription or customer by ID.\nThis API aggregates relevant events, payment methods, addresses, offers,\nand schedules to create a chronological activity history.\n- For `subscriptions` path parameter: Returns timeline for that specific subscription\n- For `customers` path parameter: Returns timeline for all subscriptions owned by that customer\n","parameters":[{"name":"path_type","in":"path","required":true,"description":"The type of entity to retrieve timeline for","schema":{"type":"string","enum":["subscriptions","customers"],"maxLength":20}},{"name":"id","in":"path","required":true,"description":"The unique identifier of the subscription or customer","schema":{"type":"string","maxLength":60}}],"responses":{"200":{"description":"Successfully retrieved timeline data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTimelineResponse"}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Subscription or customer not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}} ``` --- # Agent Instructions: 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: ``` GET https://docs.limio.com/api/objects-api/subscriptions.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.