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 three types of Orders.

Purchase - A purchase order is the first order created in the lifecycle of an agreement. The purchase order is always the first order and there is only one within an agreement.
Change - A change order is a request to update the agreement. There can be multiple change orders in an agreement.
Termination - A termination order is a request to terminate the agreement or terminate a specific subscription within the agreement. There can be multiple termination orders.

Order object

Field

Type

Description

id

string

Primary order identifier

Example: "ORD-5542-1187-3130-0991"

href

string

Relative reference to object on API (always /commerce/orders/{id})

Example: "/commerce/orders/ORD-5542-1187-3130-0991"

type

string

Specified on creation of order, cannot be updated.

Example: "Purchase"

status

string

Example: "Processing"

externalIds

ExternalIds

External IDs for either client/vendor/distributor.

Example:

{
  "client": "abc-123",
  "operations": "SO-1234-1234-1111"
}

notes

string

Contains initial customer notes added by Buyer during purchase process. Buyer can edit and add notes at any time for all order statuses. Managed by client. Not used by vendor extensions.

Example: "Order of 2 subs for 2 ppl from accounting dept."

statusNotes

Message Object

Notes added during status change by vendor or vendor extensions to indicate reason of order failure or status change. Should be shown on order screen (as part of template or standalone).

Example:

{
    "id": "E001234",
    "message": "Adobe cannot provision your subscription"
}

error

Message Object

Standard error object. Means some error appeared on parameters validation, which can include markup. Used to indicate validation error by vendor or vendor extension during order validation. Should be reflected in purchase wizard while parameters validation and on the parameters and the items screens of order. Should behave like errors in parametes, i.e. reset on order status changes.

Example:

{
    "id": "E001234",
    "message": "Order has incompatible items - eductation and goverment"
}

agreement

Agreement

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.

Example:

{
    "id": "AGR-2119-4550-8674-5962",
    "href": "/commerce/agreements/AGR-2119-4550-8674-5962",
    "name": "Microsoft Office 365 NCE E1",
    "icon": null
}

authorization

Authorization

Reference to Authorization object which was used for ther order.

Example:

{
    "id": "AUT-1234-4567",
    "href": "/authorization/ATH-1234-45678",
    "name": "Salesforce Enterprise License"
}

listing

Listing

Reference to Listing which was used for the order.

Example:

{
    "id": "LST-1234-1234"
}

template

Template

Example:

{
    "id": "TPL-1234-4444",
    "href": "/products/product/PRD-1234-1234-1234/templates/TPL-1234-4444",
    "name": "Succesful Activation"
}

assignee

User

Example:

{
    "id": "TPL-1234-4444",
    "href": "/products/product/PRD-1234-1234-1234/templates/TPL-1234-4444",
    "name": "Succesful Activation"
}

audit

AuditObject

AuditObject is a dictionary with events that happened with the object, every event has “at” part which specifies the last time the event occurred, and “by” part which specifies who the actor executed the event.

Example:

{
  "created": { "at": "...", "by": { } },
  "updated": { "at": "...", "by": { } },
  "activated": { "at": "...", "by": { } },
  "terminated": { "at": "...", "by": { } }
}

lines[]

Line[]

An Order Lines contains the information about the specific item 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

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-1234",
      "name": "Tennant Id",
      "externalId": "tennant_id",
      "value": "69b73824-ce76-4866-ad47-b615ae9d8998"
  }
]

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-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

List of subscription references, for these subscriptions that going to be added/updated by the order. On POST or PUT, lines property of subscription can be provided to reflect these changes.

Example:

[
  { "id": "SUB-5374-9558-1697-7777" },
  { "id": "SUB-5374-9558-1697-8888" },
  { "id": "SUB-5374-9558-1697-9999" }
]

price

Price

This represents the total price for an Order and is displayed to the various actors. Object is READONLY.

Please note 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

{
  "id": "ORD-6869-4529-8975-9005",
  "href": "/commerce/orders/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": { } }
  }
}

PreviousGet Subscription NextList Orders