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:
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
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
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
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
A reference to the Agreement object.
Example:
{
"id": "AGR-2119-4550-8674-5962",
"name": "Microsoft Office 365 NCE E1",
"icon": null
}authorization
A reference to the Authorization object, which was used for the order.
Example:
{
"id": "AUT-1234-4567",
"name": "Salesforce Enterprise License"
}listing
A reference to the listing that was used for the order.
Example:
{
"id": "LST-1234-1234"
}template
A reference to the Template object.
Example:
{
"id": "TPL-1234-4444",
"name": "Succesful Activation"
}assignee
A reference to the User object.
Example:
{
"id": "TPL-1234-4444",
"name": "Succesful Activation"
}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
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
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
{
"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": { } }
}
}Last updated
Was this helpful?