Orders

An order is a request made by a buyer to create/update an agreement with a one-time purchase or/and set of subscriptions. There are different types of orders in the Marketplace Platform:

• Purchase orders - An order to buy a new product or service by establishing a new agreement.

• Change orders - An order to change the quantity, such as downsizing the quantity of licenses or ordering additional licenses.

• Terminate order - An order to terminate an active subscription or an agreement.

• Configuration order - An order to enable or disable the auto-renewal of a subscription.

The Order object contains the following properties:

Field	Type	Description
id	string	The primary identifier for the order. Example: ORD-5542-1187-3130-0991
href	string	A relative reference to the object in the API. Example: /commerce/orders/ORD-5542-1187-3130-0991
type	string	The type of order. The value is specified when the order is created and cannot be updated. Example: Purchase
status	string	The status of the order. Example: Processing
externalIds	externalIds	External IDs for client/vendor/distributor. Example: { "client": "abc-123", "operations": "SO-1234-1234-1111" }
notes	string	Contains initial customer notes added by the buyer during the purchase process. Buyers can edit and add notes at any time for all order statuses. Example: Order of 2 subs for 2 ppl from the accounting dept.
statusNotes	messageObject	Notes added during status change by the vendor or vendor extensions to indicate the reason for order failure or status change. Example: { "id": "E001234", "message": "Adobe cannot provision your subscription" }
error	messageObject	Standard error object. Means some error appeared on the parameters validation, which can include markup. Used to indicate a validation error by the vendor or vendor extension during order validation. Example: { "id": "E001234", "message": "Order has incompatible items - education and government" }
agreement	agreement	A reference to the Agreement object. Example: { "id": "AGR-2119-4550-8674-5962", "name": "Microsoft Office 365 NCE E1", "icon": null }
authorization	authorization	A reference to the Authorization object, which was used for the order. Example: { "id": "AUT-1234-4567", "name": "Salesforce Enterprise License" }
listing	listing	A reference to the listing that was used for the order. Example: { "id": "LST-1234-1234" }
template	template	A reference to the Template object. Example: { "id": "TPL-1234-4444", "name": "Succesful Activation" }
assignee	user	A reference to the User object. Example: { "id": "TPL-1234-4444", "name": "Succesful Activation" }
audit	audit	A reference to the Audit object. Example: { "created": { "at": "...", "by": { } }, "updated": { "at": "...", "by": { } }, "activated": { "at": "...", "by": { } }, "terminated": { "at": "...", "by": { } } }
lines	line	Contains information about the specific item that the buyer is purchasing/updating. Example: [ { "id": "ALI-1234-1234-1234-0001", "item": { "id": "ITM-1234-1234-1234-0021", "name": "Adobe Illustrator" }, "quantity": 10, "price": { ... }, "subscription": { "id": "SUB-1234-1234-1234" } }, { "id": "ALI-1234-1234-1234-0002", "item": { "id": "ITM-4444-4444-4444-0031", "name": "Adobe Photoshop" }, "quantity": 1, "price": { ... } } ]
parameters.fulfillment	object	An object that holds a concise definition of a parameter, its value, and any associated errors. Example: [ { "id": "PRM-1234-1234-1234-1234", "name": "Tennant Id", "externalId": "tenant_id", "value": "69b73824-ce76-4866-ad47-b615ae9d8998" } ]
parameters.ordering	object	An object that holds a concise definition of a parameter, its value, and any associated errors. Example: [ { "id": "PRM-1234-1234-1234-0001", "name": "Microsoft Partner ID", "externalId": "msPartnerId", "constraints": { "readonly": false, "hidden": false, "required": true }, "value": "123456", "error": { "id": "E001234", "message": "Unknown MS Partner ID" } } ]
subscriptions	subscription	A list of references for subscriptions to be added or updated by the order. Example: [ { "id": "SUB-5374-9558-1697-7777" }, { "id": "SUB-5374-9558-1697-8888" }, { "id": "SUB-5374-9558-1697-9999" } ]
price	price	Represents the total price for the order and is displayed to the various actors. The object is READONLY. Not all fields are visible to all actors. Example: { "PPxY": 150, "PPxM": 12.50, "SPxY": 165, "SPxM": 13.75, "markup": 0.10, "margin": 0.11, "defaultMarkup": 0.15, "currency": "USD" }

Example

ORDER OBJECT

{
  "id": "ORD-6869-4529-8975-9005",
  "agreement": {
    "id": "AGR-2119-4550-8674-5962",
    "name": "Microsoft Office 365 NCE E1"
  },
  "type": "Purchase",
  "status": "Processing",
  "statusNotes": {
    "id": "ERR-123-123",
    "message": "Vendor API is not responding. Try later"
  },
  "template": {
    "id": "TPL-1234-4444",
    "name": "Activation in Progress"
  },
  "assignee": {
    "id": "USR-1234-1234-1234",
    "name": "John Smith",
    "icon": "/static/users/USR-1234-1234-1234.icon.svg"
  },
  "lines": [
      {  // Upsize
        "id": "ALI-1234-1234-1234-0001",
        "item": {
          "id": "ITM-1234-1234-1234-0021",
          "name": "Adobe Illustrator"
        },
        "quantity": 10,
        "price": { ... },
        "subscription": { "id": "SUB-1234-1234-1234" }
      },
      {   // New purchase
        "id": "ALI-1234-1234-1234-0002",
        "item": {
          "id": "ITM-4444-4444-4444-0031",
          "name": "Adobe Photoshop"
        },
        "quantity": 1,
        "price": { ... }
      }
  ],
  "notes": "Order for accounting team",
  "parameters": {
    "fulfillment": [
      {
        "id": "PRM-1234-1234-1234-1234",
        "name": "Tennant Id",
        "externalId": "tennant_id",
        "value": "69b73824-ce76-4866-ad47-b615ae9d8998"
      }
    ],
    "ordering": [
      {
        "id": "PRM-1234-1234-1234-0001",
        "name": "Microsoft Partner ID",
        "externalId": "msPartnerId",
        "constraints": {
            "readonly": false,
            "hidden": false,
            "required": true
        },
        "value": "123456",
        "error": {
            "id": "E001234",
            "message": "Unknown MS Partner ID"
        }
      }
    ]
  },
  "externalIDs": {
    "client": "abc-123",
    "operations": "SO-1234-1234-1111"
  },
  "audit": {
    "created": { "at": "...", "by": { } },
    "updated": { "at": "...", "by": { } },
    "activated": { "at": "...", "by": { } },
    "terminated": { "at": "...", "by": { } }
  }
}