Orders

An order is a request to create a new agreement or update an agreement to include a one-time purchase or set of subscriptions. There are different types of orders in the SoftwareOne Marketplace:

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

This object contains the following attributes:

Field Name	Data 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	externalIds 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	object (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	object (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	object	A reference to the agreement object. Example: { "id": "AGR-2119-4550-8674-5962", "name": "Microsoft Office 365 NCE E1", "icon": null }
authorization	object	A reference to the authorization object, which was used for the order. Example: { "id": "AUT-1234-4567", "name": "Salesforce Enterprise License" }
listing	object	A reference to the listing that was used for the order. Example: { "id": "LST-1234-1234" }
template	object	A reference to the template object. Example: { "id": "TPL-1234-4444", "name": "Successful Activation" }
assignee	object	A reference to the user object. Example: { "id": "TPL-1234-4444", "name": "Successful Activation" }
audit	object	A reference to the audit object.
lines	object	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	object	A list of references for subscription 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	object	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" }
termsAndConditions	object	Represents the terms and conditions in published state of the product being accepted as a part of the order. The terms are accepted on an order at the point of order creation and also at the point when the order is set to the processing state. Example: [ { "id": "TCS-3159-1891-0980-8679", "accepted": "2024-04-29T15:37:16.071Z", "acceptedBy": { "id": "USR-0000-0001", "href": "/accounts/users/USR-0000-0001", "name": "Will Smith" }, "name": "Microsoft 365 Terms of Service" } ]

Example response

{
  "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": "tenant_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"
  },
  "termsAndConditions":[
  {
     "id": "TCS-3159-1891-0980-8679",   
     "accepted": "2024-04-29T15:37:16.071Z",
     "acceptedBy": {
        "id": "USR-0000-0001",
        "href": "/accounts/users/USR-0000-0001",
        "name": "Will Smith"
      },
      "name": "Microsoft 365 Terms of Service"
    }
  ],
  "audit": {
    "created": { "at": "...", "by": { } },
    "updated": { "at": "...", "by": { } }
  }
}