Subscriptions

The Subscriptions object represents a collection of product items within the agreement.

All items are connected to one product, one vendor, and one client (same as the agreement) and have a common billing frequency and commitment terms. The Subscriptions object contains the following properties:

Field	Type	Description
id	string	The identifier for the subscription object. Example: SUB-2119-4550-8674-5962
href	string	Relative reference to the object in the API. Example: /v1/commerce/subscriptions/SUB-2119-4550-8674-5962)
status	string	The key status of the object. Possible values are a by-product of the latest completed order that included this subscription. Possible statuses are a subset of all subscription statuses. Example: Active
name	string	The name of the subscription. Example: Subscription for Microsoft Office 365 NCE E1
agreement	agreement	The agreement that contains this particular subscription. Example: { "id": "AGR-2119-4550-8674-5962", "name": "Microsoft Office 365 for My Company" }
product	product	Reference to the Product object. Example: { "id": "PRD-1111-1111-1111", "name": "Microsoft Office 365 NCE", "icon": "/static/PRD-1111-1111-1111/logo.png" }
startDate	string	The start date of the subscription. Example: 2023-12-14T17:28:57Z
commitmentDate	string	The date when the subscription commitment ends and the subscription needs to be renewed. Example: 2023-12-14T17:28:57Z
terminationDate	string	The date when the subscription is to be terminated. Example: 2023-12-14T17:28:57Z
terms	terms	The subscription's billing terms. Example: { "period": "1m", "commitment": "1y" }
price	price	The price of the subscription. Example: { "PPxY": 150, "PPxM": 12.50, "SPxY": 165, "SPxM": 13.75, "markup": 0.10, "margin": 0.11, "defaultMarkup": 0.15, "currency": "USD" }
lines	lines	A list of all product items (lines) purchased in the scope of this subscription. Example: [ { "id": "ALI-1234-1234-1234-0001", "item": { "id": "ITM-1234-1234-1234-0021", "name": "Adobe Illustrator" }, "quantity": 10, "price": { ... } }, { "id": "ALI-1234-1234-1234-0002", "item": { "id": "ITM-4444-4444-4444-0031", "name": "Adobe Photoshop" }, "quantity": 1, "price": { ... } } ]
parameters	object	An object that groups separate lists of parameters. Only fulfillment parameters are available in this object. Example: { "fulfillment": [...] }
parameters.fulfillment	object	An object that holds a concise definition of a parameter, its value, and any associated errors. Example: { "name": "New Subscription", "value": "Super_value_UPDATED", "constraints": { "readonly": false, "hidden": true, "required": true, "unique": false } }
audit	audit	Audit object with possible entries: created, updated, activated, terminated, according to the object's lifecycle. Example: { "created": { "at": "...", "by": { } }, "updated": { "at": "...", "by": { } }, "activated": { "at": "...", "by": { } }, "terminated": { "at": "...", "by": { } } }
externalIDs	externalIDs	Set of external IDs. Example: { "client": "12345678", "vendor": "ABC-2023-C07-dbeee0b302c0" }

Example

SUBSCRIPTION OBJECT

{
  "id": "SUB-5903-9370-1653-5455",
  "name": "Subscription for Avast Pro",
  "status": "Updating",
  "startDate": "2025-10-05T04:46:24.0758413+02:00",
  "renewalDate": "2024-03-20T08:47:50.7092432+01:00",
  "terms": {
    "period": "1m",
    "commitment": "1y"
  },
  "price": {
    "margin": 0.01,
    "markup": 0.011,
    "SPxM": 1708.12,
    "SPxY": 20504.00,
    "PPxM": 7.12,
    "PPxY": 88.00,
    "defaultMarkup": 0.15,
    "currency": "USD"
  },
  "externalIDs": {
    "client": "12345678",
    "vendor": "ABC-2023-C07-dbeee0b302c0"
  },,
  "agreement": {
    "id": "AGR-8808-0693-9072-0018",
  },
  "order": {
    "id": "ORD-8556-1262-1387-2499",
    "type": "Purchase",
    "status": "Draft",
    "clientReferenceNumber": null,
    "notes": null
  },
  "lines": [
    {
      "id": "ALI-1234-1234-1234-0001",
      "item": {
        "id": "ITM-1234-1234-1234-0021",
        "name": "Adobe Illustrator"
      },
      "quantity": 10,
      "price": {
        "PPxY": 150,
        "PPxM": 12.50,
        "unitPP": 1.25
        "SPxY": 165,
        "SPxM": 13.50,
        "unitSP": 1.35,
        "markup": 0.10,
        "margin": 0.11,
        "currency": "USD"
      }
    },
    {
      "id": "ALI-1234-1234-1234-0002",
      "item": {
        "id": "ITM-4444-4444-4444-0031",
        "name": "Adobe Photoshop"
      },
      "price": {
        "PPxY": 150,
        "PPxM": 12.50,
        "unitPP": 12.50
        "SPxY": 165,
        "SPxM": 13.50,
        "unitSP": 13.50,
        "markup": 0.10,
        "margin": 0.11,
        "currency": "USD"
      }
    }
  ]
}