Agreements

Agreements Object

The agreement represents an instance of a relationship between Seller, Buyer, and Licensee. It may refer to one-time purchases or/and set of subscriptions.

Field	Type	Description
id	string	Primary account identifier. Example: "AGR-2119-4550-8674"
href	string	Relative reference to object on API (always /commerce/agreements/{id}). Example: "/v1/commerce/agreements/AGR-2119-4550-8674"
status	string	The key status of the object. May only be specified on creation - Draft or Provisioning, and cannot be updated with PUT.
name	string	Agreement name, will be assigned automatically on creation, as {product.name} for {licensee.name} but can be changed later. Example: "Microsoft Office 365 NCE E1"
vendor	Account	Reference to the vendor Account object filled-in on creation according product. Example: { "id": "ACC-1234-1234", "href": "/accounts/accounts/ACC-1234-1234", "name": "Microsoft", "icon": "/static/ACC-1234-1234/account.png" }
client	Account	Reference to the Client Account object. Example: { "id": "ACC-1234-4444", "href": "/accounts/accounts/ACC-1234-4444", "name": "Best LLC", "icon": "/static/ACC-1234-4444/account.png" }
buyer	Buyer	Reference to Buyer object. Example: { "id": "BUY-3731-7971", "href": "/accounts/buyers/BUY-3731-7971", "name": "Adam Ruszczak", "icon": "/static/BUY-3731-7971/icon.png" }
seller	Seller	Reference to the Seller object. Example: { "id": "SEL-9121-8944", "href": "/accounts/sellers/SEL-9121-8944", "name": "Software LN", "icon": "/static/SEL-9121-8944/icon.png" }
licensee	Licensee	Reference to the Licensee object. Example: { "id": "LCE-9625-9634", "href": "/accounts/licensees/LCE-9625-9634", "name": "John Smith", "icon": "/static/LCE-9625-9634/icon.png" }
product	Product	Reference to the Product object. Example: { "id": "PRD-1111-1111-1111", "href": "/catalog/products/PRD-1111-1111-1111", "name": "Microsoft Office 365 NCE", "icon": "/static/PRD-1111-1111-1111/logo.png" }
listing	Listing	Reference to the listing which allows this agreement. Example: { "id": "LST-1234-1234" }
authorization	Authorization	Reference to the Authorization object used for the agreement. Example: { "id": "AUT-1234-4567", "href": "/authorization/ATH-1234-45678", "name": "Salesforce Enterprise License" }
price	Price	The price for the agreement, explains the monthly and yearly prices for the whole agreement, one-time price tags are never included into it. different parts of price object visible to different actors, see Price Object. Example: { "PPxY": 150, "PPxM": 12.50, "SPxY": 165, "SPxM": 13.75, "currency": "USD" }
template	Template	Reference to Template object. Example: { "id": "TPL-1234-4444", "href": "/products/product/<id>/templates/TPL-1234-4444", "name": "Succesful Activation" }
error	ErrorObject	Markup text string explaining reason for provisining failure. Always set on moving status to Failed. Example: { "id": "E001234", "message": "Agreement provisioning failed due to unavailability of the item" }
lines	Lines[]	List of items in Agreement. Example: [ { "id": "ALI-1234-1234-1234-0127", "item": { "id": "ITM-1234-1234-1234-0992", "name": "Adobe Migration" }, "quantity": 10, "price": { "PPx1": 12.50, "unitPP": 1.25 "SPx1": 13.50, "unitSP": 1.35, "currency": "USD" }, "order": { "id": "ORD-6869-4529-8975-9005" } } ]
subscriptions	Subscription[]	Example: [ { "id": "SUB-0792-5000-2253", "href": "/commerce/agreements/AGR-2119-4550-8674-5962/subscriptions/SUB-0792-5000-2253" } ]
parameters.fulfillment	OrderParameterValue []	An object that holds a concise definition of a parameter, its value, and any associated errors. Example: [ { "id": "PRM-1234-1234-1234", "name": "Tennant Id", "externalId": "tennant_id", "constraints": { "readonly": false, "hidden": true, "required": true, "unique": false }, "value": "69b73824-ce76-4866-ad47-b615ae9d8998", "error": { "id": "E001234", "message": "Incorrect parameter value" } } ]
parameters.ordering	Order Parameter Object []	An object that holds a concise definition of a parameter, its value, and any associated errors. Example: [ { "id": "PRM-1234-1234-1234", "name": "Tennant Id", "externalId": "tennant_id", "constraints": { "readonly": false, "hidden": true, "required": true, "unique": false }, "value": "69b73824-ce76-4866-ad47-b615ae9d8998", "error": { "id": "E001234", "message": "Incorrect parameter value" } } ]
audit	AuditObject	Audit object with possible entries: created, updated, activated, terminated, according to the object's lifecycle. Possible audit events include Created, Updated, Activated, Terminated, and Failed. Example: { "created": { "at": "...", "by": { } }, "updated": { "at": "...", "by": { } }, "activated": { "at": "...", "by": { } }, "terminated": { "at": "...", "by": { } } }
externalIds	ExternalIdsObject	Set of external IDs. Example: { "client": "12345678", "operations": "07bf766b-c767-4293-9ab3", "vendor": "ABC-2023-C07-dbeee0b302c0" }

Example

SHORT FORM

{
  "id": "AGR-2119-4550-8674",
  "href": "/commerce/agreements/AGR-2119-4550-8674",
  "status": "Draft",
  "name": "Microsoft Office 365 NCE E1", 
  "vendor": { "id": "ACC-1234-1234" },
  "client": { "id": "ACC-1234-4444" },
  "seller": { "id": "SEL-9121-8944" },
  "buyer": { "id": "BUY-3731-7971" },
  "licensee": { "id": "LCE-9625-9634" },
  "product": {
    "id": "PRD-1111-1111-1111",
    "href": "/catalog/products/PRD-1111-1111-1111",
    "name": "Microsoft Office 365 NCE",
    "icon": "/static/PRD-1111-1111-1111/logo.png"
  },
  "price": {
    "PPxY": 150,
    "PPxM": 12.50,
    "SPxY": 165,
    "SPxM": 13.75,
    "currency": "USD"
  },
  "startDate": "2023-12-14T17:28:57.667Z",
  "endDate": "2023-12-14T17:28:57.667Z",
  "template": {
    "id": "TPL-1234-4444",
    "href": "/products/product/<id>/templates/TPL-1234-4444",
    "name": "Succesful Activation"
  },
  "audit": {
    "created": { "at": "...", "by": { } },
    "updated": { "at": "...", "by": { } }
  },
  "lines": [
    {
      "id": "ALI-1234-1234-1234-0127",
      "item": {
        "id": "ITM-1234-1234-1234-0992",
        "name": "Adobe Migration"
      },
      "quantity": 10,
      "price": {
        "PPx1": 12.50,
        "unitPP": 1.25
        "SPx1": 13.50,
        "unitSP": 1.35,
        "currency": "USD"
      },
      "order": { "id": "ORD-6869-4529-8975-9005" }
    }
  ],
  "subscriptions": [
    { "id": "SUB-0792-5000-2253" }
  ],
  "parameters": {
    "ordering": [ ],
    "fulfillment": [ ]
  },
  "externalIDs": {
    "client": "12345678",
    "operations":	"07bf766b-c767-4293-9ab3",
    "vendor": "ABC-2023-C07-dbeee0b302c0"
  }
}

LONG EXAMPLE

{
  "id": "AGR-2119-4550-8674",
  "href": "/commerce/agreements/AGR-2119-4550-8674",
  "status": "Draft",
  "name": "Microsoft Office 365 NCE E1", 
  "vendor": {
    "id": "ACC-1234-1234",
    "href": "/accounts/accounts/ACC-1234-1234",
    "name": "Microsoft",
    "icon": "/static/ACC-1234-1234/account.png"
  },
  "client": {
    "id": "ACC-1234-4444",
    "href": "/accounts/accounts/ACC-1234-4444",
    "name": "Best LLC",
    "icon": "/static/ACC-1234-4444/account.png"
  },
  "seller": {
    "id": "SEL-9121-8944",
    "href": "/accounts/sellers/SEL-9121-8944",
    "name": "Software LN",
    "icon": "/static/SEL-9121-8944/icon.png"
  },
  "buyer": {
    "id": "BUY-3731-7971",
    "href": "/accounts/buyers/BUY-3731-7971",
    "name": "Adam Ruszczak",
    "icon": "/static/BUY-3731-7971/icon.png"
  },
  "licensee": {
    "id": "LCE-9625-9634",
    "href": "/accounts/licensees/LCE-9625-9634",
    "name": "John Smith",
    "icon": "/static/LCE-9625-9634/icon.png"
  },
  "product": {
    "id": "PRD-1111-1111-1111",
    "href": "/catalog/products/PRD-1111-1111-1111",
    "name": "Microsoft Office 365 NCE",
    "icon": "/static/PRD-1111-1111-1111/logo.png"
  },
  "price": {
    "PPxY": 150,
    "PPxM": 12.50,
    "SPxY": 165,
    "SPxM": 13.75,
    "markup": 0.10,
    "margin": 0.11,
    "currency": "USD"
  },
  "startDate": "2023-12-14T17:28:57.667Z",
  "endDate": "2023-12-14T17:28:57.667Z",
  "template": {
    "id": "TPL-1234-4444",
    "href": "/products/product/<id>/templates/TPL-1234-4444",
    "name": "Succesful Activation"
  },
  "audit": {
    "created": { 
      "at": "2023-12-14T17:28:57Z", 
      "by": {
        "id": "UR-1234-1234-1234",
        "name": "John Smith",
        "icon": "/static/users/UR-1234-1234-1234.icon.svg"
      }
    },
    "updated": { 
      "at": "2023-12-14T17:28:57Z", 
      "by": {
        "id": "UR-1234-1234-1234",
        "name": "John Smith",
        "icon": "/static/users/UR-1234-1234-1234.icon.svg"
      }
    }
  },
  "lines": [
    {
      "id": "ALI-1234-1234-1234-0127",
      "item": {
        "id": "ITM-1234-1234-1234-0992",
        "name": "Adobe Migration"
      },
      "quantity": 10,
      "price": {
        "PPx1": 12.50,
        "unitPP": 1.25,
        "SPx1": 13.50,
        "unitSP": 1.35,
        "markup": 0.10,
        "margin": 0.11,
        "currency": "USD"
      },
      "order": { "id": "ORD-6869-4529-8975-9005" }
    }
  ],
  "subscriptions": [
    {
      "id": "SUB-0792-5000-2253",
      "href": "/commerce/agreements/AGR-2119-4550-8674-5962/subscriptions/SUB-0792-5000-2253"
    }
  ],
  "parameters": {
    "ordering": [
      {
        "id": "string",
        "name": "string",
        "value": "string",
        "hasError": true,
        "description": {
          "type": "SingleLine",
          "phase": "Configuration",
          "isRequired": true,
          "isHidden": true,
          "isReadOnly": true,
          "error": "string"
        }
      }
    ],
    "fulfillment": [
      {
        "id": "string",
        "name": "string",
        "value": "string",
        "hasError": true,
        "description": {
          "type": "SingleLine",
          "phase": "Configuration",
          "isRequired": true,
          "isHidden": true,
          "isReadOnly": true,
          "error": "string"
        }
      }
    ]
  },
  "externalIDs": {
    "client": "12345678",
    "operations":	"07bf766b-c767-4293-9ab3",
    "vendor": "ABC-2023-C07-dbeee0b302c0"
  }
}