| description |
Use the Commerce API to manage orders, subscriptions, and agreements programmatically. |
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.
Review the shared API docs before you work with commerce 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.
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:
View Assets operations
| Operation | Method | Description | Access |
|---|
| Create asset | POST | Creates an active asset that is globally retrievable. | vendor |
| List assets | GET | Gets all assets. | vendor, client, ops |
| Get asset by id | GET | Gets an asset by id. | vendor, client, ops |
| Update asset | PUT | Updates an asset by id. | vendor, client, ops |
| Terminate asset | POST | Sets an asset’s status to terminated and terminates all related entitlements. | vendor |
| Render asset template | GET | Renders an asset’s template by id. | vendor, client, ops |
View Agreements operations
| Operation | Method | Description | Access |
|---|
| Create agreement | POST | Creates an agreement administratively. | ops |
| List agreements | GET | Gets a list of agreements. | vendor, client, ops |
| Get agreement by id | GET | Gets an agreement by id. | vendor, client, ops |
| Update agreement | PUT | Updates some properties of an agreement. | vendor, client, ops |
| Render agreement template | GET | Renders the template for an agreement by id. | vendor, client, ops |
| Create agreement attachment | POST | Creates an agreement attachment by uploading a file. | vendor, ops |
| List agreement attachments | GET | Gets a list of agreement attachments. | vendor, client, ops |
| Get agreement attachment by id | GET | Gets an agreement attachment by id. | vendor, client, ops |
| Delete agreement attachment | DELETE | Deletes an agreement attachment. | vendor, ops |
View Orders operations
| Operation |
Method |
Description |
Access |
| Create order |
POST |
Creates a new order for a specified agreement or creates an agreement. |
client |
| List orders |
GET |
Gets a list of orders visible to the user. |
vendor, client, ops |
| Get order by id |
GET |
Gets an order by id. |
vendor, client, ops |
| Update order |
PUT |
Updates some properties of an order. |
vendor, client, ops |
| Validate order |
POST |
Validates the state of an order. |
vendor, client, ops |
| Process order |
POST |
Changes an order’s status to processing. |
vendor, client, ops |
| Query order |
POST |
Changes an order’s status to querying. |
vendor |
| Complete order |
POST |
Changes an order’s status to complete. |
vendor |
| Fail order |
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 |
DELETE |
Deletes an order. |
client |
| Render order template |
GET |
Renders the template for an order by id. |
vendor, client, ops |
View Order Subscriptions operations
View Order Assets operations
| Operation |
Method |
Description |
Access |
| Create order asset |
POST |
Creates a draft asset that is only retrievable through the order. |
vendor |
| List order assets |
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 |
PUT |
Updates an order asset by id. |
vendor, client, ops |
| Delete order asset |
DELETE |
Deletes an order asset by id. |
vendor |
View Requests operations
| Operation |
Method |
Description |
Access |
| Create request |
POST |
Creates a new request. |
client, ops |
| List requests |
GET |
Gets a list of requests. |
vendor, client, ops |
| Get request by id |
GET |
Gets a request by id. |
vendor, client, ops |
| Update request |
PUT |
Updates some properties of a request. |
vendor, ops |
| Validate request |
POST |
Performs the request validation procedure. |
vendor, client, ops |
| Process request |
POST |
Moves a request to the processing state. |
vendor, client, ops |
| Query request |
POST |
Moves a request to the querying state. |
vendor, ops |
| Complete request |
POST |
Moves a request to the completed state. |
vendor, client, ops |
View Subscriptions operations