> For the complete documentation index, see [llms.txt](https://docs.platform.softwareone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform.softwareone.com/developer-resources/rest-api/commerce-api.md).

# Commerce API

The **Commerce API** enables you to create, retrieve, and manage orders, subscriptions, and agreements within the Marketplace Platform.

With this API, you can:

* Create new assets and manage the existing ones.
* Check the details of a specific order by its ID.
* Delete orders that are still in draft status (not yet submitted).
* Fail orders that can't be completed.
* Update, process, or complete orders as needed.
* Retrieve and manage files attached to agreements.
* Validate requests and manage the status of those requests.

## Before you start

Review the shared API docs before you work with commerce resources.

* [Authentication](/developer-resources/rest-api.md)
* [URL structure](/developer-resources/api-usage-and-reference/url-structure.md)
* [Error handling](/developer-resources/api-usage-and-reference/errors-handling.md)

## Core resources

The Commerce API is built around the following core resources:

* **Agreement** – Defines the relationship between the `seller`, `buyer`, and `licensee`.
* **Asset** – Represents a one-time purchased item or a perpetual license associated with an agreement.
* **Order** – Represents a request to create or modify an agreement, including purchasing, changing, or terminating `subscriptions` within an agreement.
* **Order asset** – Represents an asset created and managed in the context of an order.
* **Order subscription** – Represents a subscription created and managed in the context of an order.
* **Request** – Represents a request to the platform.
* **Subscription** – Represents a collection of items within the agreement. All items are connected to one `product`, one vendor, and one client, and share the same billing frequency and commitment terms.

## Browse collections

The API is organized into collections, each containing a set of operations. Access to these operations varies by role, depending on whether you are a `client`, `vendor`, or `operations` user.

Use the following links to jump to the collection you need:

* [Assets](#assets)
* [Agreements](#agreements)
* [Orders](#orders)
* [Order Subscriptions](#order-subscriptions)
* [Order Assets](#order-assets)
* [Requests](#requests)
* [Subscriptions](#subscriptions)

### Assets

<details>

<summary>View Assets operations</summary>

<table><thead><tr><th width="158">Operation</th><th width="127">Method</th><th width="232">Description</th><th>Access</th></tr></thead><tbody><tr><td><a href="/pages/Ql13jrckroPv99DPJPVF">Create asset</a></td><td>POST</td><td>Creates an active asset that is globally retrievable.</td><td>vendor</td></tr><tr><td><a href="/pages/TY8VO05f30t03HMiKeLe">List assets</a></td><td>GET</td><td>Gets all assets.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/6xgra7qHSbRkexIAYTVP">Get asset by id</a></td><td>GET</td><td>Gets an asset by id.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/Ni3m0Foc6BcmiGwPmsrC">Update asset</a></td><td>PUT</td><td>Updates an asset by id.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/vdJ3KAlwudxuEgX8n12s">Terminate asset</a></td><td>POST</td><td>Sets an asset’s status to terminated and terminates all related entitlements.</td><td>vendor</td></tr><tr><td><a href="/pages/kIcTegSkZ6meqODnMMS4">Render asset template</a></td><td>GET</td><td>Renders an asset’s template by id.</td><td>vendor, client, ops</td></tr></tbody></table>

</details>

### Agreements

<details>

<summary>View Agreements operations</summary>

<table><thead><tr><th width="218">Operation</th><th width="124">Method</th><th>Description</th><th>Access</th></tr></thead><tbody><tr><td><a href="/pages/JzDJUxAAcGOZIovoA3Ml">Create agreement</a></td><td>POST</td><td>Creates an agreement administratively.</td><td>ops</td></tr><tr><td><a href="/pages/nYHvWdpiBFyjsr3Pv6CD">List agreements</a></td><td>GET</td><td>Gets a list of agreements.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/7ORgHE2Wjs8V5uoobslz">Get agreement by id</a></td><td>GET</td><td>Gets an agreement by id.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/oJyymVOR0H8VK21Yamgz">Update agreement</a></td><td>PUT</td><td>Updates some properties of an agreement.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/HY8PEsmt6UAHF1T4nsEK">Render agreement template</a></td><td>GET</td><td>Renders the template for an agreement by id.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/VGBjiudEWZOLf0DSEK7c">Create agreement attachment</a></td><td>POST</td><td>Creates an agreement attachment by uploading a file.</td><td>vendor, ops</td></tr><tr><td><a href="/pages/ty1Uv3wp0u8VTeHaGKWJ">List agreement attachments</a></td><td>GET</td><td>Gets a list of agreement attachments.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/3wXDBMIRXuHmSh2WPDw7">Get agreement attachment by id</a></td><td>GET</td><td>Gets an agreement attachment by id.</td><td>vendor, client, ops</td></tr><tr><td><a href="/pages/ujlgwdrhlVfHZ9vbDQvC">Delete agreement attachment</a></td><td>DELETE</td><td>Deletes an agreement attachment.</td><td>vendor, ops</td></tr></tbody></table>

</details>

### Orders

<details>

<summary>View Orders operations</summary>

| Operation                                                                                           | Method | Description                                                            | Access              |
| --------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------- | ------------------- |
| [Create order](/developer-resources/rest-api/commerce-api/orders/create-new-order.md)               | POST   | Creates a new order for a specified agreement or creates an agreement. | client              |
| [List orders](/developer-resources/rest-api/commerce-api/orders/list-orders.md)                     | GET    | Gets a list of orders visible to the user.                             | vendor, client, ops |
| [Get order by id](/developer-resources/rest-api/commerce-api/orders/get-order.md)                   | GET    | Gets an order by id.                                                   | vendor, client, ops |
| [Update order](/developer-resources/rest-api/commerce-api/orders/update-order.md)                   | PUT    | Updates some properties of an order.                                   | vendor, client, ops |
| [Validate order](/developer-resources/rest-api/commerce-api/orders/validate-order.md)               | POST   | Validates the state of an order.                                       | vendor, client, ops |
| [Process order](/developer-resources/rest-api/commerce-api/orders/process-order.md)                 | POST   | Changes an order’s status to processing.                               | vendor, client, ops |
| [Query order](/developer-resources/rest-api/commerce-api/orders/query-order.md)                     | POST   | Changes an order’s status to querying.                                 | vendor              |
| [Complete order](/developer-resources/rest-api/commerce-api/orders/complete-order.md)               | POST   | Changes an order’s status to complete.                                 | vendor              |
| [Fail order](/developer-resources/rest-api/commerce-api/orders/fail-order.md)                       | POST   | Changes an order’s status to failed.                                   | vendor, ops         |
| Notify client about order                                                                           | POST   | Sends an email reminder to the client.                                 | ops                 |
| [Delete order](/developer-resources/rest-api/commerce-api/orders/delete-order.md)                   | DELETE | Deletes an order.                                                      | client              |
| [Render order template](/developer-resources/rest-api/commerce-api/orders/render-order-template.md) | GET    | Renders the template for an order by id.                               | vendor, client, ops |

</details>

### Order Subscriptions

<details>

<summary>View Order Subscriptions operations</summary>

| Operation                                                                                                          | Method | Description                                                            | Access              |
| ------------------------------------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------- | ------------------- |
| [Create order subscription](/developer-resources/rest-api/commerce-api/subscriptions/create-order-subscription.md) | POST   | Creates a new subscription and adds it to the order.                   | vendor              |
| [List order subscriptions](/developer-resources/rest-api/commerce-api/subscriptions/list-subscriptions-1.md)       | GET    | Returns a list of all subscriptions for the order visible to the user. | vendor, client, ops |
| [Get order subscription by id](/developer-resources/rest-api/commerce-api/subscriptions/get-order-subscription.md) | GET    | Returns a subscription with the given id that exists in the order.     | vendor, client, ops |
| [Update order subscription](/developer-resources/rest-api/commerce-api/subscriptions/update-order-subscription.md) | PUT    | Updates an existing subscription within the order.                     | vendor              |
| [Remove order subscription](/developer-resources/rest-api/commerce-api/subscriptions/remove-order-subscription.md) | DELETE | Removes a subscription from the order.                                 | vendor              |

</details>

### Order Assets

<details>

<summary>View Order Assets operations</summary>

| Operation                                                                                     | Method | Description                                                       | Access              |
| --------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- | ------------------- |
| [Create order asset](/developer-resources/rest-api/commerce-api/orders/create-order-asset.md) | POST   | Creates a draft asset that is only retrievable through the order. | vendor              |
| [List order assets](/developer-resources/rest-api/commerce-api/orders/list-order-assets.md)   | GET    | Gets all order assets.                                            | vendor, client, ops |
| Get order asset by id                                                                         | GET    | Gets an order asset by id.                                        | vendor, client, ops |
| [Update order asset](/developer-resources/rest-api/commerce-api/orders/update-order-asset.md) | PUT    | Updates an order asset by id.                                     | vendor, client, ops |
| [Delete order asset](/developer-resources/rest-api/commerce-api/orders/delete-order-asset.md) | DELETE | Deletes an order asset by id.                                     | vendor              |

</details>

### Requests

<details>

<summary>View Requests operations</summary>

| Operation                                                                                   | Method | Description                                | Access              |
| ------------------------------------------------------------------------------------------- | ------ | ------------------------------------------ | ------------------- |
| [Create request](/developer-resources/rest-api/commerce-api/requests/create-request.md)     | POST   | Creates a new request.                     | client, ops         |
| [List requests](/developer-resources/rest-api/commerce-api/requests/list-requests.md)       | GET    | Gets a list of requests.                   | vendor, client, ops |
| [Get request by id](/developer-resources/rest-api/commerce-api/requests/get-request.md)     | GET    | Gets a request by id.                      | vendor, client, ops |
| [Update request](/developer-resources/rest-api/commerce-api/requests/update-request.md)     | PUT    | Updates some properties of a request.      | vendor, ops         |
| [Validate request](/developer-resources/rest-api/commerce-api/requests/validate-request.md) | POST   | Performs the request validation procedure. | vendor, client, ops |
| [Process request](/developer-resources/rest-api/commerce-api/requests/process-request.md)   | POST   | Moves a request to the processing state.   | vendor, client, ops |
| [Query request](/developer-resources/rest-api/commerce-api/requests/query-request.md)       | POST   | Moves a request to the querying state.     | vendor, ops         |
| [Complete request](/developer-resources/rest-api/commerce-api/requests/complete-request.md) | POST   | Moves a request to the completed state.    | vendor, client, ops |

</details>

### Subscriptions

<details>

<summary>View Subscriptions operations</summary>

| Operation                                                                                                                 | Method | Description                                     | Access              |
| ------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | ------------------- |
| [Create subscription](/developer-resources/rest-api/commerce-api/subscriptions/create-subscription.md)                    | POST   | Creates a subscription.                         | vendor              |
| [List subscriptions](/developer-resources/rest-api/commerce-api/subscriptions/list-subscriptions.md)                      | GET    | Gets a list of subscriptions in all agreements. | vendor, client, ops |
| [Get subscription by id](/developer-resources/rest-api/commerce-api/subscriptions/get-subscription.md)                    | GET    | Gets a subscription in an agreement by id.      | vendor, client, ops |
| [Update subscription](/developer-resources/rest-api/commerce-api/subscriptions/update-subscription.md)                    | PUT    | Updates a subscription.                         | vendor, client, ops |
| [Terminate subscription](/modules-and-features/marketplace/subscriptions/terminate-a-subscription.md)                     | POST   | Terminates a subscription.                      | vendor              |
| [Render subscription template](/developer-resources/rest-api/commerce-api/subscriptions/render-subscriptions-template.md) | GET    | Renders a subscription’s template.              | vendor, client, ops |

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform.softwareone.com/developer-resources/rest-api/commerce-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.