# 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 <token>`"}},"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.<br>

```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 <token>`"}},"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<br>

```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 <token>`"}},"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"}}}}}}
```