Create Order | Cancel Order Item | Update Order Status | Update Prints Remaining | Get Orders | Get Order Items | Get All Products Ordered by User
Current version 0.1
Note: consumption of all the endpoints below requires a valid security header.
The order management API endpoints enable the following actions:
Supplying an actual score for rendering within your site, whether for preview or for post-purchase full render, is handled by the /viewer endpoints.
Endpoint security signature: ["createorder"][your key]
This endpoint is used to create an order.
If your customer is purchasing multiple different products, you will need to call this endpoint for each different product purchased.
Note: To complete the purchase, a second call to the /viewer/scp/registerpurchase endpoint is currently required.
When making a call to this endpoint, the following parameters are required:
Important: although we provide prices in non-GBP currencies, you will be billed according to the GBP base price.
A license string is a short piece of text describing the purchase. It is embedded in the footer of every page of the purchased score. For example:
Supplied by [Your company name here] for [your customer name here]. Order number [your order number]. Copies purchased: [number of copies purchased].
- where the square brackets and their contents above are replaced with your data at runtime.
Please note: this parameter must be URL encoded. Spaces should be encoded as "%20", not "+".
If you do not provide a license string, one will be created for you. It is not currently possible to update a license string once it has been created.
License strings will be generated automatically on first access for all your customer's purchases which pre-date the release of this API.
Example call: https://api.sheetmusicdirect.com/orders/create?key=[your_key_here]&retailerOrderId=[your_order_id_here]&retailerClientId=[your_client_id_here]&productId=[productId]&quantity=1&countryCode=GB&licenseString=[url-encoded_license_string]
Example response:
[Http status code = 201]
OK: order created
Endpoint security signature: ["cancelorder"][your key]
This endpoint is used to cancel an entire order.
Making a call to this endpoint will set all items in an order to cancelled.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders/cancel?key=[your_key_here]&retailerOrderId=[your_order_id_here]&retailerClientId=[your_client_id_here]
Example response:
[Http status code = 200]
OK: order cancelled
Endpoint security signature: ["cancelorderitem"][your key]
This endpoint is used to cancel a single item which is part of a larger order.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders/cancel/item?key=[your_key_here]&retailerOrderId=[your_order_id_here]&retailerClientId=[your_client_id_here]&productId=[productId]
Example response:
[Http status code = 200]
OK: order item cancelled
Endpoint security signature: ["update"][your key]
This endpoint is used to update the status of an order.
You may use this method if, for example, you wish to allow customers to pay offline by cheque. Once you have created the order, use this method to set the order status to pending. When payment has been received, use this call to amend the status again. See below for a list of order status codes.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders/update?key=[your_key_here]&retailerOrderId=[your_order_id_here]&retailerClientId=[your_client_id_here]
Example response:
[Http status code = 200]
OK: order updated
There are three endpoints which can be used for retrieving order information:
The /orders endpoint returns a list of all orders.
The /orders/orderitems endpoint returns a list of all purchased products within a specific order.
The /orders/allproducts endpoint returns a list of all products purchased by a specific user.
Endpoint security signature: ["orders"][your key]
This endpoint is used to get a list of orders placed by your customer. Orders are returned in descending date of purchase.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders?key=[your_key_here]&retailerClientId=[your_client_id_here]
Example response:
[HTTP status code = 200]
{
"orders": [
{
"RetailerOrderId": "6a4554b7-e155-4a97-a1e3-c54b02567eba",
"DateCreated": "2015-10-13T19:28:29",
"OrderStatus": 8
},
{
"RetailerOrderId": "1d58b0fd-ede7-46cb-b715-38ce606969ed",
"DateCreated": "2015-10-13T19:28:26",
"OrderStatus": 64
}
]
}
Endpoint security signature: ["orders-orderitems"][your key]
This endpoint is used to get a list of items in a specific order placed by your customer.
When making a call to this endpoint, the following parameters are required:
Because this endpoint deals only with a specific order, to reduce data repetition, the order ID is returned once only as an additional root node element.
Example call: https://api.sheetmusicdirect.com/orders/orderitems?key=[your_key_here]&retailerClientId=[your_client_id_here]
Example response:
[HTTP status code = 200]
{
"order id": "6a4554b7-e155-4a97-a1e3-c54b02567eba",
"orderitems": [
{
"RetailerOrderId": null,
"ProductId": 13618,
"QuantityOrdered": 1,
"PrintsRemaining": 1,
"OrderStatus": 8,
"CatalogueReference": "smd_000001"
},
{
"RetailerOrderId": null,
"ProductId": 13621,
"QuantityOrdered": 1,
"PrintsRemaining": 1,
"OrderStatus": 8,
"CatalogueReference": "smd_000001"
}
]
}
Endpoint security signature: ["orders-allproducts"][your key]
This endpoint is used to get all products which your customer has ordered. Ordered items are returned in descending date of purchase.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders/allproducts?key=[your_key_here]&retailerClientId=[your_client_id_here]
Example response:
[HTTP status code = 200]
{
"orderedProducts": [
{
"RetailerOrderId": "6a4554b7-e155-4a97-a1e3-c54b02567eba",
"ProductId": 13618,
"QuantityOrdered": 1,
"PrintsRemaining": 1,
"OrderStatus": 8,
"CatalogueReference": "smd_000001"
},
{
"RetailerOrderId": "1d58b0fd-ede7-46cb-b715-38ce606969ed",
"ProductId": 13621,
"QuantityOrdered": 1,
"PrintsRemaining": 1,
"OrderStatus": 64,
"CatalogueReference": "smd_000001"
}
]
}
Endpoint security signature: ["updateprintsremaining"][your key][retailerClientId][retailerOrderId][productId]
This endpoint is used to reset the number of prints for a specific order item.
When making a call to this endpoint, the following parameters are required:
Example call: https://api.sheetmusicdirect.com/orders/updateprintsremaining?key=[your_key_here]&retailerOrderId=[your_order_id_here]&retailerClientId=[your_client_id_here]&productId=[productId]&printsRemaining=[printsRemaining]
Example response:
[Http status code = 200]
OK: prints remaining was reset