Orderspace API
Welcome to the Orderspace API reference. This document contains everything needed to access and use the API.
Getting Started
Add a Custom Integration from the Integrations section of the Orderspace admin to provide access to the API.
The Orderspace API supports two types of integration, Private and Public.
Private Integrations
Private Integrations are designed for custom integrations with a specific Orderspace site. Authentication is performed by exchanging the integration's keys directly for an access token. This kind of integration should be used when working directly with a trusted developer on an integration designed specifically for your site.
Public Integrations
Public Integrations are designed for integrations with third-party products and services where the integration can be used by any Orderspace site. Authentication uses OAuth2 Authorization Code grant flow, allowing the admin user of any Orderspace site to authorize the integration through the web site.
If you are developing an integration for use by multiple Orderspace sites, start off with a Private Integration and contact us to have it upgraded to a Public Integration.
Request/Response Format
The Orderspace API is organised around REST using predictable resource-oriented URLS and standard HTTP response codes.
The base URL for all API requests is https://api.orderspace.com/v1/
Requests with a message body, such as create or update requests, use JSON in the message body and should have an HTTP header with Content-Type: application/json
Responses are returned in JSON format
Many endpoints accept optional parameters which can be passed as part of the HTTP query string. For example, GET https://api.orderspace.com/v1/orders?created_since=2021-04-08
. The available parameters are detailed in the documentation for each endpoint.
Dates and times are in ISO 8601 format. Times are specified in UTC time regardless of the time zone set on the Orderspace account
IDs are provided for each resource as a unique, randomly generated string containing letters and numbers. IDs are prefixed with a two letter code representing the resource type, for example cu_dnwz8gnx
represents a customer record.
Pagination
Endpoints that return multiple records have a limit on the number of records returned. Cursor based pagination can be used to obtain additional records. The following HTTP query parameters are used:
limit
controls the number of records returned. For most endpoints the default is 50 and the maximum is 200 per page.starting_after
is a cursor used to obtain the next page of records. This should be set to the ID of the last record in the list to obtain the next page of records. For example, when requesting orders, if the ID of the last order isor_342q9r46
,GET https://api.orderspace.com/v1/orders?starting_after=or_342q9r46
will return the next page of orders
Errors
When an error occurs, an HTTP status code other than 200 will be used in the response. The message body will contain a JSON representation of the error message.
Code | Description |
---|---|
400 Bad Request | The request was unacceptable, often due to malformed JSON input or missing required parameters |
401 Unauthorized | The access token was invalid or missing |
404 Not Found | The requested endpoint or resource was not found |
422 Unprocessable Entity | The request could not be processed due to errors, for example validation errors when creating or updating a resource |
429 Too Many Requests | See the section on throttling |
500 Internal Server Error | Something went wrong at our end |
Throttling
API requests are limited to a maximum of 60 requests per minute. Clients exceeding this limit will receive an HTTP 429 response. We recommend spacing out requests to avoid hitting the limit. If an HTTP 429 response is received, wait at least 60 seconds before sending any additional requests.
Authentication
Private Integrations
Obtain an access token
curl -X POST https://identity.orderspace.com/oauth/token \
-d client_id=CLIENT_ID \
-d client_secret=CLIENT_SECRET \
-d grant_type=client_credentials
Example response
{
"access_token": "WUECFd_Z1G02cxcKt2rFOy-Tn-zOAbjrCKUJB5S264U",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "read write"
}
Example of using an access token with an API request
curl https://api.orderspace.com/v1/customers \
-H "Authorization: Bearer WUECFd_Z1G02cxcKt2rFOy-Tn-zOAbjrCKUJB5S264U"
Private Integrations are authenticated using the OAuth2 Client Credentials grant flow.
To obtain an access token, post the integration's Client ID and Client Secret to the identity server. This will return a JSON response with the access token. The token can be used to access the API using an HTTP Authorization header.
Access tokens are valid for 30 minutes. They should be stored and used for all requests to the API within the next 30 minutes. When an access token has expired, a new token can be requested by posting the client credentials to the identity server again. If an expired token is used to access the API, an HTTP 401 response will be returned.
Customers
A customer represents a company placing orders through your Orderspace site
The Customer Object
Example customer
{
"customer": {
"id": "cu_dnwz8gnx",
"company_name": "Blue Sky",
"created_at": "2021-03-09T13:08:51Z",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"tax_rate_id": null,
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}
-
id string
Unique auto-generated identifier for the customer -
company_name string
The customer's company name -
created_at string
The UTC date and time the customer was created in ISO 8601 format -
status string
The status of the customer, one ofnew
,active
orclosed
-
reference string
Your reference for this customer. Visible to the customer but not editable by them -
internal_note string
An internal note for this customer. Not visible to the customer -
buyers list
The buyer associated with this customer. This represents a user that can log in and access the ordering site. Currently Orderspace has a restriction of a single buyer per customer, but this parameter is a list to support multiple buyers per customer in the future. Adding more than one buyer to the list will currently fail.Child Attributes of Buyers
-
buyer.name string
The full name of the user -
buyer.email_address string
The email address associated with this user. This must be unique across all customers and buyers as it is used for logging in to the ordering site
-
-
phone string
The customer's phone number -
email_addresses hash
The customer's email addressesChild Attributes
-
orders string
The customer's email address for order confirmations. Multiple email addresses may be present, separated by commas -
dispatches string
The customer's email address for dispatch confirmations. Multiple email addresses may be present, separated by commas -
invoices string
The customer's email address for invoices. Multiple email addresses may be present, separated by commas
-
-
tax_number string
The customer's sales tax or VAT number -
tax_rate_id string
Set to null to use the default tax rates set on each product, or the ID of a Tax Rate to use a specific rate. This should be set to null unless the customer needs to be assigned a specific rate, for example if they are in another country. -
addresses list
The customer's addressesChild Attributes
-
address.company_name string
Company name -
address.contact_name string
Contact name -
address.line1 string
Address line 1 -
address.line2 string
Address line 2 -
address.city string
City, town or village -
address.state string
State, county, province or region. U.S., Canadian and Australian addresses should use the abbreviated form of the state -
address.postal_code string
ZIP or postal code -
address.country string
Two-letter ISO 3166-1 country code
-
-
minimum_spend number
The customer's minimum spend per order in the currency of the price list assigned to them or the account default currency if no price list is assigned. Set tonull
if there is no minimum spend -
payment_terms_id string
The ID of the Payment Terms assigned to this customer. Set tonull
if no Payment Terms are assigned -
customer_group_id string
The ID of the Customer Group assigned to this customer. Set tonull
if no Customer Group is assigned -
price_list_id string
The ID of the Price List assigned to this customer. Set tonull
if no Price List is assigned
Create a customer
Example request with curl
curl -X POST https://api.orderspace.com/v1/customers \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"company_name": "Blue Sky",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}'
Example success response [HTTP 200 Success]
{
"customer": {
"id": "cu_dnwz8gnx",
"company_name": "Blue Sky",
"created_at": "2021-03-09T13:08:51Z",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"tax_rate_id": null,
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}
Example error response [HTTP 422 Unprocessable Entity]
{
"message": "Validation failed: Email address has already been taken"
}
Create a new customer
HTTP Request
POST https://api.orderspace.com/v1/customers
Response
HTTP 200 Success
- The customer object in JSON format
HTTP 422 Unprocessable Entity
- A message describing the errors
List customers
Example request with curl
curl -X GET https://api.orderspace.com/v1/customers \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-d limit=20 \
-d starting_after=cu_53zjgvnm
Example success response [HTTP 200 Success]
{
"customers": [
{
"id": "cu_dnwz8gnx",
"company_name": "Blue Sky",
"created_at": "2021-03-09T13:08:51Z",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"tax_rate_id": null,
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
},
{...},
{...}
],
"has_more": true
}
Retrieve a list of customers. Customers are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/customers
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last customer in the list will retrieve the next page of customers -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
company_name optional
Return customers with the specified company name -
buyers_email_address optional
Return customers with the specified buyers email address -
status optional
Return customers with the specified status, one ofnew
,active
orclosed
-
reference optional
Return customers with the specified reference -
payment_terms_id optional
Return customers with the specified payment terms -
customer_group_id optional
Return customers in the specified group -
price_list_id optional
Return customers with the specified price list
Response
HTTP 200 Success
- A list of customers in JSON format
Retrieve a customer
Example request with curl
curl -X GET https://api.orderspace.com/v1/customers/cu_dnwz8gnx \
-H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{
"customer": {
"id": "cu_dnwz8gnx",
"company_name": "Blue Sky",
"created_at": "2021-03-09T13:08:51Z",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"tax_rate_id": null,
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}
Retrieve a single customer by ID
HTTP Request
GET https://api.orderspace.com/v1/customers/:customer_id
Response
HTTP 200 Success
- The customer record in JSON format
HTTP 404 Not Found
- A message describing the error
Update a customer
Example request with curl
curl -X PUT https://api.orderspace.com/v1/customers/cu_53zjgvnm \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"company_name": "Blue Sky",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}'
Example success response [HTTP 200 Success]
{
"customer": {
"id": "cu_dnwz8gnx",
"company_name": "Blue Sky",
"created_at": "2021-03-09T13:08:51Z",
"status": "active",
"reference": "",
"internal_note": "",
"buyers": [
{
"name": "Emilia Jane Dogherty",
"email_address": "sample@orderspace.com"
}
],
"phone": "12345",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"tax_number": "",
"tax_rate_id": null,
"addresses": [
{
"company_name": "Blue Sky",
"contact_name": "Emilia Jane Dogherty",
"line1": "12 Blue Sky Lane",
"line2": "",
"city": "Bristol",
"postal_code": "BS1 2DF",
"state": "",
"country": "GB"
}
],
"minimum_spend": 150.0,
"payment_terms_id": "pt_zkmqv8e0",
"customer_group_id": "cg_w2n6ln8v",
"price_list_id": "pr_3715yj58"
}
}
Example error response [HTTP 422 Unprocessable Entity]
{
"message": "Validation failed: Email address has already been taken"
}
Update an existing customer. Any fields not included in the update will remain the same.
HTTP Request
PUT https://api.orderspace.com/v1/customers/:customer_id
Response
HTTP 200 Success
- The customer object in JSON format
HTTP 422 Unprocessable Entity
- A message describing the errors
Orders
The Order Object
Example order
{
"order": {
"id": "or_l5DYqeDn",
"number": 1204,
"created": "2020-04-08T15:03:55Z",
"status": "new",
"customer_id": "cu_gpbOljAn"
"company_name": "Sample Customer",
"phone": "07911 123456",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"created_by": "Sample User",
"delivery_date": "2020-04-09",
"reference": "",
"internal_note": "",
"customer_po_number": "",
"customer_note": "",
"standing_order_id": "or_68ogydlx",
"shipping_type": "Special Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"billing_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "336 Hargrave Rd",
"line2": "Windsor",
"city": "New York",
"state": "NY",
"postal_code": "13865",
"country": "US"
},
"order_lines": [
{
"id": "ol_NdOLvlpw",
"sku": "AM-D-CHR-10",
"name": "Amelia Dress",
"options": "Colour: Charcoal, Size: 10",
"grouping_category": {
"id": "ca_9n1klwr5",
"name": "Dresses"
},
"shipping": false,
"quantity": 10,
"unit_price": 30.0,
"sub_total": 300.0,
"tax_rate_id": "tr_qk85g0k7",
"tax_name": "Standard",
"tax_rate": 20.0,
"tax_amount": 60.0,
"preorder_window_id": "",
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
}
],
"currency": "GBP",
"net_total": 306.1,
"gross_total": 366.1
}
}
-
id string
Unique auto-generated identifier for the order -
number number
Unique number identifying the order, shown to the customer -
created string
The date and time the order was placed in ISO 8601 format -
status string
The status of the order, one ofnew
,invoiced
,released
,part_fulfilled
,preorder
,fulfilled
,standing_order
orcancelled
-
customer_id string
Internal identifier for the related customer resource -
company_name string
The customer's company name -
phone string
The customer's phone number -
email_addresses hash
The customer's email addressesChild Attributes
-
orders string
The customer's email address for order confirmations. Multiple email addresses may be present, separated by commas -
dispatches string
The customer's email address for dispatch confirmations. Multiple email addresses may be present, separated by commas -
invoices string
The customer's email address for invoices. Multiple email addresses may be present, separated by commas
-
-
created_by string
The name of the user that created this order -
delivery_date string
The customer requested delivery date in ISO 8601 format -
reference string
Your reference for this order. Visible to the customer but not editable by them -
internal_note string
Your internal note for this order, not visible to the customer -
customer_po_number string
The customer's purchase order number for this order -
customer_note string
The customer's note on this order -
standing_order_id string
Internal identifier for the standing order used to generate this repeat order. Set to null if this is not a repeat order. Only present if the standing orders feature is enabled -
shipping_type string
The name of the shipping option selected for this order -
shipping_address hash
The order's shipping address.Child Attributes
-
shipping_address.company_name string
Company name -
shipping_address.contact_name string
Contact name -
shipping_address.line1 string
Address line 1 -
shipping_address.line2 string
Address line 2 -
shipping_address.city string
City, town or village -
shipping_address.state string
State, county, province or region. U.S., Canadian and Australian addresses should use the abbreviated form of the state -
shipping_address.postal_code string
ZIP or postal code -
shipping_address.country string
Two-letter ISO 3166-1 country code
-
-
billing_address hash
The order's billing addressChild Attributes
-
billing_address.company_name string
Company name -
billing_address.contact_name string
Contact name -
billing_address.line1 string
Address line 1 -
billing_address.line2 string
Address line 2 -
billing_address.city string
City, town or village -
billing_address.state string
State, county, province or region. U.S., Canadian and Australian addresses should use the abbreviated form of the state -
billing_address.postal_code string
ZIP or postal code -
billing_address.country string
Two-letter ISO 3166-1 country code
-
-
order_lines list
List of the individual lines that make up the order asorder lines
Child Attributes of Order Lines
-
order_line.id string
Internal identifier for the order line -
order_line.sku string
The unique code for the ordered item -
order_line.name string
The name of the ordered item -
order_line.options string
The options (size/color etc) of the ordered item -
order_line.grouping_category hash
The grouping category for this order line. Only present if the "group products on orders" feature is enabledChild Attributes of Grouping Category
-
order_line.grouping_category.id string
Internal identifier for the category -
order_line.grouping_category.name string
The name of the category
-
-
order_line.shipping boolean
Indicates whether the order line represents a shipping charge -
order_line.quantity number
The number of items ordered -
order_line.unit_price number
The unit price of each item on this line -
order_line.sub_total number
The line sub-total excluding tax -
order_line.tax_rate_id string
The id of the tax rate applied to this order line -
order_line.tax_name string
The name of the tax rate applied to this order line -
order_line.tax_rate number
The tax rate applied to this order line as a percentage -
order_line.tax_amount number
The total tax applied to this order line -
order_line.preorder_window_id string
The id of the preorder window applied to this order line. If set, items are preorders that should not have stock allocated to them or be fulfilled until they are released -
order_line.on_hold boolean
Indicates whether the items are on hold. If set to true, the items are preorders that should not have stock allocated to them or be fulfilled -
order_line.invoiced number
The number of items invoiced -
order_line.paid number
The number of items paid for via invoices -
order_line.dispatched number
The number of items dispatched
-
-
currency string
The three-letter ISO currency code representing the order's currency -
net_total number
The total cost of all items on the order excluding tax -
gross_total number
The total cost of all items on the order including tax
Create an order
Example request with curl
curl -X POST "https://api.orderspace.com/v1/dispatches" \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"order": {
"customer_id": "cu_m3xgel1w",
"delivery_date": "2022-09-13",
"reference": "test reference",
"internal_note": "test internal note",
"customer_po_number": "test customer po number",
"customer_note": "test customer note",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"billing_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "336 Hargrave Rd",
"line2": "Windsor",
"city": "New York",
"state": "NY",
"postal_code": "13865",
"country": "US"
},
"order_lines": [
{ "sku": "TC01-BLU-S", "quantity": 9 },
{ "name": "Custom Item Name", quantity: 10, unit_price: 2.00, tax_rate_id: "tr_ruo96bhf" },
{ "name": "Special Delivery", "unit_price": 4.9, "shipping": true },
{...},
{...}
]
}
}'
Example HTTP 200 success response
{
"order": {
"id": "or_v8zqdw8r",
"number": 1204,
"created": "2022-09-13T08:03:33Z",
"status": "new",
"customer_id": "cu_m3xgel1w",
"company_name": "T1C1 Ltd",
"phone": "0115 2781234",
"email_addresses": {
"orders": "test_customer1@orderspace.com",
"dispatches": "test_customer1@orderspace.com",
"invoices": "test_customer1@orderspace.com"
},
"created_by": null,
"delivery_date": "2022-09-15",
"reference": "test reference",
"internal_note": "test internal note",
"customer_po_number": "test customer po number",
"customer_note": "test customer note",
"shipping_type": "Special Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"billing_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "336 Hargrave Rd",
"line2": "Windsor",
"city": "New York",
"postal_code": "13865",
"state": "NY",
"country": "US"
},
"order_lines": [
{
"id": "ol_z1o7jxrp",
"sku": "TC01-BLU-S",
"name": "Trench Coat",
"options": "Colour: Blue, Size: Small",
"shipping": false,
"quantity": 9,
"unit_price": 1.1,
"sub_total": 9.9,
"tax_rate_id": "tr_qk85g0k7",
"tax_name": "Standard",
"tax_rate": 20.0,
"tax_amount": 1.98,
"preorder_window_id": "",
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
},
{
"id": "ol_fhb69our",
"sku": "",
"name": "Custom Item",
"options": "",
"shipping": false,
"quantity": 10,
"unit_price": 2.0,
"sub_total": 20.0,
"tax_rate_id": "tr_ruo96bhf",
"tax_name": "Reduced",
"tax_rate": 5.0,
"tax_amount": 1.0,
"preorder_window_id": "",
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
},
{
"id": "ol_9mq3971w",
"sku": "",
"name": "International Courier Delivery",
"options": "",
"shipping": true,
"quantity": 1,
"unit_price": 4.9,
"sub_total": 4.9,
"tax_rate_id": "tr_qk85g0k7",
"tax_name": "Standard",
"tax_rate": 20.0,
"tax_amount": 0.98,
"preorder_window_id": "",
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
},
{...},
{...}
],
"currency": "GBP",
"net_total": 274.95,
"gross_total": 322.28
}
}
Example HTTP 422 error response
{
"message": "TC02-BLU-S - No longer available,TC02-BLU-M - No longer available"}
}
Orders must be associated with an existing customer using customer_id
If number
is not provided, an order number will be automatically generated using the next available number. We recommend this approach whenever possible to avoid order number conflicts
Items on order_lines
are identified using sku
. Product ID and Product Variant ID are not required. Use name
instead of sku
to add a custom item or charge, not connected to a product on the system. Use name
combined with "shipping": true
to add a shipping charge.
HTTP Request
POST https://api.orderspace.com/v1/orders
Response
HTTP 200 Success
- The order object in JSON format
HTTP 422 Unprocessable Entity
- A message describing the errors
List orders
Example request with curl
curl -X GET https://api.orderspace.com/v1/orders \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-d limit=20 \
-d starting_after=or_jl663xl1
Example success response [HTTP 200 Success]
{
"orders": [
{
"id": "or_l5DYqeDn",
"number": 1204,
"created": "2020-04-08T15:03:55Z",
"status": "new",
"customer_id": "cu_gpbOljAn"
"company_name": "Sample Customer",
"phone": "07911 123456",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"created_by": "Sample User",
"delivery_date": "2020-04-09",
"reference": "",
"internal_note": "",
"customer_po_number": "",
"customer_note": "",
"standing_order_id": null,
"shipping_type": "Special Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"billing_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "336 Hargrave Rd",
"line2": "Windsor",
"city": "New York",
"state": "NY",
"postal_code": "13865",
"country": "US"
},
"order_lines": [
{
"id": "ol_NdOLvlpw",
"sku": "AM-D-CHR-10",
"name": "Amelia Dress",
"options": "Colour: Charcoal, Size: 10",
"grouping_category": {
"id": "ca_9n1klwr5",
"name": "Dresses"
},
"shipping": false,
"quantity": 10,
"unit_price": 30.0,
"sub_total": 300.0,
"tax_rate_id": "tr_qk85g0k7"
"tax_name": "Standard",
"tax_rate": 20.0,
"tax_amount": 60.0,
"preorder_window_id": "",
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
}
],
"currency": "GBP",
"net_total": 306.1,
"gross_total": 366.1
},
{...},
{...}
],
"has_more": true
}
Retrieve a list of orders. Orders are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/orders
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last order in the list will retrieve the next page of orders -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
created_before optional
Return records created before the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
delivery_date_since optional
Return records with a delivery date after the specified date in ISO 8601 format, e.g.2019-10-29
-
delivery_date_before optional
Return records with a delivery date before the specified date in ISO 8601 format, e.g.2019-10-27
-
number optional
Return records with the specified order number -
status optional
Return records with the specified status, one ofnew
,invoiced
,released
,part_fulfilled
,preorder
,fulfilled
,standing_order
orcancelled
-
reference optional
Return records with the specified reference -
customer_id optional
Return records for the specified customer -
standing_order_id optional
Return repeat orders generated by the specified standing order. This option is only applicable if the standing orders feature is enabled
Response
HTTP 200 Success
- A list of orders in JSON format
Retrieve an order
curl -X GET https://api.orderspace.com/v1/orders/or_l5DYqeDn \
-H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{
"order": {
"id": "or_l5DYqeDn",
"number": 1204,
"created": "2020-04-08T15:03:55Z",
"status": "new",
"customer_id": "cu_gpbOljAn"
"company_name": "Sample Customer",
"phone": "07911 123456",
"email_addresses": {
"orders": "sample@orderspace.com",
"dispatches": "sample@orderspace.com",
"invoices": "sample@orderspace.com",
},
"created_by": "Sample User",
"delivery_date": "2020-04-09",
"reference": "",
"internal_note": "",
"customer_po_number": "",
"customer_note": "",
"shipping_type": "Special Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"billing_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "336 Hargrave Rd",
"line2": "Windsor",
"city": "New York",
"state": "NY",
"postal_code": "13865",
"country": "US"
},
"order_lines": [
{
"id": "ol_NdOLvlpw",
"sku": "AM-D-CHR-10",
"name": "Amelia Dress",
"options": "Colour: Charcoal, Size: 10",
"grouping_category": {
"id": "ca_9n1klwr5",
"name": "Dresses"
},
"shipping": false,
"quantity": 10,
"unit_price": 30.0,
"sub_total": 300.0,
"tax_name": "Standard",
"tax_rate": 20.0,
"tax_amount": 60.0,
"on_hold": false,
"invoiced": 0,
"paid": 0,
"dispatched": 0
}
],
"currency": "GBP",
"net_total": 306.1,
"gross_total": 366.1
}
}
Retrieve a single order by ID
HTTP Request
GET https://api.orderspace.com/v1/orders/:order_id
Response
HTTP 200 Success
- The order record in JSON format
HTTP 404 Not Found
- A message describing the error
Dispatches
A dispatch represents items on an order being fulfilled
The Dispatch Object
Example JSON Response
{
"dispatch": {
"id": "di_4kzzxdk2",
"order_id": "or_wlvzog4g",
"order_number": 1289,
"created": "2021-04-16T12:58:39Z",
"comments": "Sent by Royal Mail using Next Day Delivery",
"customer_note": "",
"customer_po_number": "",
"shipping_type": "Next Day Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"email_address": "sample@orderspace.com",
"phone": "07911 123456",
"dispatch_lines": [
{
"order_line_id": "ol_z1ow2pdm",
"sku": "ZAG-D-16",
"name": "Angelica Dress",
"options": "Size: 16",
"quantity": 1
},
{
"order_line_id": "ol_nm427o01",
"sku": "ZAG-D-18",
"name": "Angelica Dress",
"options": "Size: 18",
"quantity": 2
},
{
"order_line_id": "ol_pmvznz21",
"sku": "ZAG-D-20",
"name": "Angelica Dress",
"options": "Size: 20",
"quantity": 3
},
]
}
}
-
order_id string
Internal identifier for the related order -
comments string
Comments to be shown on the delivery note and the dispatch email sent to the customer. This can contain courier details and tracking info, and anything else that the customer needs to know -
customer_po_number string
The customer's purchase order number for the related order -
customer_note string
The customer's note on the related order -
shipping_type string
The name of the shipping option selected for the related order -
shipping_address hash
The shipping address for the related orderChild Attributes
-
shipping_address.company_name string
Company name -
shipping_address.contact_name string
Contact name -
shipping_address.line1 string
Address line 1 -
shipping_address.line2 string
Address line 2 -
shipping_address.city string
City, town or village -
shipping_address.state string
State, county, province or region. U.S., Canadian and Australian addresses should use the abbreviated form of the state -
shipping_address.postal_code string
ZIP or postal code -
shipping_address.country string
Two-letter ISO 3166-1 country code
-
-
email_address string
The customer's email address for the related order -
phone string
The customer's phone number for the related order -
dispatch_lines list
Child Attributes
-
dispatch_line.order_line_id string
Internal identifier for the order line being dispatched -
dispatch_line.sku string
The SKU of the item being dispatched -
dispatch_line.name string
The name of the item being dispatched -
dispatch_line.options string
The options (size/color etc) of the item being dispatched -
dispatch_line.quantity number
The number of items being dispatched
-
Create a dispatch
Example request with curl
curl -X POST "https://api.orderspace.com/v1/dispatches" \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dispatch": {
"order_id": "or_wlvzog4g",
"comments": "Sent by Royal Mail using Next Day Delivery",
"dispatch_lines": [
{"sku": "ZAG-D-16", "quantity": 1},
{"sku": "ZAG-D-18", "quantity": 2},
{"sku": "ZAG-D-20", "quantity": 3},
]
}
}'
Example HTTP 200 success response
{
"dispatch": {
"id": "di_4kzzxdk2",
"order_id": "or_wlvzog4g",
"order_number": 1289,
"created": "2021-04-16T12:58:39Z",
"comments": "Sent by Royal Mail using Next Day Delivery",
"customer_note": "",
"customer_po_number": "",
"shipping_type": "Next Day Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"email_address": "sample@orderspace.com",
"phone": "07911 123456",
"dispatch_lines": [
{
"order_line_id": "ol_z1ow2pdm",
"sku": "ZAG-D-16",
"name": "Angelica Dress",
"options": "Size: 16",
"quantity": 1
},
{
"order_line_id": "ol_nm427o01",
"sku": "ZAG-D-18",
"name": "Angelica Dress",
"options": "Size: 18",
"quantity": 2
},
{
"order_line_id": "ol_pmvznz21",
"sku": "ZAG-D-20",
"name": "Angelica Dress",
"options": "Size: 20",
"quantity": 3
},
]
}
}
Example HTTP 422 error response
{
"message": "The order has already been fulfilled"
}
Create a dispatch. This will mark the order lines as dispatched and reduce the stock on hand representing the items leaving your warehouse. The status of the related order will change to fulfilled
if all items on the order have been dispatched. A dispatch confirmation email will be sent to the customer if this setting is enabled.
Many of the fields on the dispatch object are read only and can not be set when a dispatch is created. See the example for the fields that can be set. All other fields come from the order and are for reference only.
HTTP Request
POST https://api.orderspace.com/v1/dispatches
Response
HTTP 200 Success
- The dispatch object in JSON format
HTTP 422 Unprocessable Entity
- A message describing the errors
List dispatches
Example request with curl
curl -X GET https://api.orderspace.com/v1/dispatches \
-H "Authorization: Bearer {ACCESS TOKEN}" \
-d limit=20 \
-d starting_after=cu_53zjgvnm
Example HTTP 200 success response
{
"dispatches": [
{
"id": "di_4kzzxdk2",
"order_id": "or_wlvzog4g",
"order_number": 1289,
"created": "2021-04-16T12:58:39Z",
"comments": "Sent by Royal Mail using Next Day Delivery",
"customer_note": "",
"customer_po_number": "",
"shipping_type": "Next Day Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"email_address": "sample@orderspace.com",
"phone": "07911 123456",
"dispatch_lines": [
{
"order_line_id": "ol_z1ow2pdm",
"sku": "ZAG-D-16",
"name": "Angelica Dress",
"options": "Size: 16",
"quantity": 1
},
{
"order_line_id": "ol_nm427o01",
"sku": "ZAG-D-18",
"name": "Angelica Dress",
"options": "Size: 18",
"quantity": 2
},
{
"order_line_id": "ol_pmvznz21",
"sku": "ZAG-D-20",
"name": "Angelica Dress",
"options": "Size: 20",
"quantity": 3
}
]
},
{...},
{...}
]
}
Retrieve a list of dispatches. Dispatches are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/dispatches
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last dispatch in the list will retrieve the next page of dispatches -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
created_before optional
Return records created before the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
order_id optional
Return dispatches for the specified order
Retrieve a dispatch
curl -X GET https://api.orderspace.com/v1/dispaches/di_4kzzxdk2 \
-H "Authorization: Bearer {ACCESS TOKEN}"
Example HTTP 200 success response
{
"dispatch": {
"id": "di_4kzzxdk2",
"order_id": "or_wlvzog4g",
"order_number": 1289,
"created": "2021-04-16T12:58:39Z",
"comments": "Sent by Royal Mail using Next Day Delivery",
"customer_note": "",
"customer_po_number": "",
"shipping_type": "Next Day Delivery",
"shipping_address": {
"company_name": "Sample Customer",
"contact_name": "",
"line1": "34 Edgar Buildings",
"line2": "George Street",
"city": "Bath",
"state": "",
"postal_code": "BA1 2FJ",
"country": "GB"
},
"email_address": "sample@orderspace.com",
"phone": "07911 123456",
"dispatch_lines": [
{
"order_line_id": "ol_z1ow2pdm",
"sku": "ZAG-D-16",
"name": "Angelica Dress",
"options": "Size: 16",
"quantity": 1
},
{
"order_line_id": "ol_nm427o01",
"sku": "ZAG-D-18",
"name": "Angelica Dress",
"options": "Size: 18",
"quantity": 2
},
{
"order_line_id": "ol_pmvznz21",
"sku": "ZAG-D-20",
"name": "Angelica Dress",
"options": "Size: 20",
"quantity": 3
},
]
}
}
Retrieve a single dispatch by ID
HTTP Request
GET https://api.orderspace.com/v1/dispatches/:dispatch_id
Response
HTTP 200 Success
- The dispatch record in JSON format
HTTP 404 Not Found
- A message describing the error
Products
Products represent items for sale. Products contain product variants which represent a specific version of a product with unique properties, e.g. colors and sizes. Products with no variations contain a single product variant.
Some of the fields on the product object are read only and can not be set when a product is created. See the example for the fields that can be set.
The Product Object
Example product
{
"product": {
"id": "pr_lj3pwm1n",
"code": "AD01",
"name": "Alexa Dress",
"description": "Summer colours, fully lined",
"active": true,
"tariff_code": "0804.401",
"country_of_origin": "India",
"composition": "100% cotton",
"variant_options": ["Color", "Size"],
"product_variants": [
{
"id": "pv_v18kxq1e",
"sku": "AD01-10",
"barcode": "123456789",
"options": {"Color": "Red", "Size": "10"},
"unit_price": 32.0,
"price_list_prices": [
{"id": "pr_z0j7yjl2", "unit_price": 35.0}
],
"rrp": 72.0,
"backorder": true,
"minimum": 4,
"multiple": 3,
"weight": 0.0,
},
{
"id": "pv_xjz5xvjk",
"sku": "AD01-12",
"barcode": "1123456789",
"options": {"Color": "Red", "Size": "12"},
"unit_price": 32.0,
"price_list_prices": [],
"rrp": 72.0,
"backorder": true,
"minimum": 2,
"multiple": 2,
"weight": 0.0,
},
{
"id": "pv_q1l2n634",
"sku": "AD01-14",
"barcode": "2123456789",
"options": {"Color": "Red", "Size": "14"},
"unit_price": 32.0,
"price_list_prices": [],
"rrp": 72.0,
"backorder": true,
"minimum": 4,
"multiple": null,
"weight": 1.0,
}
],
"categories": [
{
"id": "ca_x61lk8j7",
"name": "Dresses"
},
{
"id": "ca_3xwy7mwo",
"name": "Spring / Summer 2022"
}
],
"grouping_category_id": "ca_x61lk8j7",
"images": [
"https://a1b2c3d4ef.cloudfront.net/accountname/images/products/image_name-8vr0j3wd.jpg",
"https://a1b2c3d4ef.cloudfront.net/accountname/images/products/another_image_name-eorkg2nv.png"
]
}
}
-
id string
Unique auto-generated identifier for the product -
code string
A unique code to represent the product -
name string
The name of the product -
description string
Details of the product shown on product pages -
active boolean
Controls the visibility of the product to customers -
minimum number
The minimum order quantity required for this product. Set to null for no minimum. Minimums are set account-wide to either per product or per variant. This field is only present on the product when the setting is per product -
tariff_code string
The tariff code for commercial invoices. Set to null to use the default tariff code. Only visible if the commercial invoices feature is enabled -
country_of_origin string
The country of origin for commercial invoices. Set to null to use the default country of origin. Only visible if the commercial invoices feature is enabled -
composition string
The composition of the product for commercial invoices. Set to null to use the default composition. Only visible if the commercial invoices feature is enabled -
variant_options list
A list of the ways in which the product varies (Color, Size etc). Products can have zero, one, two or three variant options. The order of the options in the list is significant as this controls how the products are displayed on ordering tables. The order should be the same throughout your products so that ordering tables are consistent. For example, if products vary by Color and Size, always list Color first and Size second.product_variants list
Product Variants represent a specific version of a product based on the variant options you have specified. For example, if the options are Color and Size, there should be one product variant for each specific color and size your product contains (for example Red, Small). Products with no variant options should have a single product variant withoptions
left empty.Child Attributes
-
id string
Unique auto-generated identifier for the product variant -
sku string
A unique code to represent the product variant. Often this is a combination of the product code and a suffix representing the unique variant, for example AD01-RED-S to represent product code AD01 with color red and size small. -
barcode string
Optional barcode number (EAN/UPC/GTIN) representing this product variant -
options hash
A hash listing the options that make this variant unique. The keys should match the product'svariant_options
and the combination of values must be unique to this variant. For example, if the variant options are Color and Size, a specific variant could be{"Color": "Red", "Size": "Small"}
-
unit_price number
The wholesale price of the product variant -
price_list_prices list
A list of price list prices set for this product variant. If a price is not listed here, the price will default to the standard unit price multiplied by the price list conversion rateChild Attributes
-
id string
The ID of the price list -
unit_price number
The unit price of the product variant for this price list. Set tonull
to remove the price set here and revert back to the calculated price of unit price multiplied by price list conversion rate
rrp number
The recommended retail price for the product variantbackorder boolean
Determines if the product variant can be ordered when there is no stock available. Set to false, only the stock available can be orderedminimum number
The minimum order quantity required for this variant. Set to null for no minimum. Minimums are set account-wide to either per product or per variant. This field is only present on variants when the setting is per variantmultiple number
weight number
The weight of this variant in kg. Used for shipping price calculationstax_rate_id string
The tax rate id to be used for this item. Should be set to null to use the default tax rate unless a specific tax rate is requiredlocation string
A string representing the location of this item in the warehouse, used for picking. This field is only present if the stock locations feature is enabled -
-
categories list
A list of categories the product is listed inChild Attributes
-
id string
The ID of the category -
name string
The name of the category
grouping_category_id string
The ID of the category used for grouping on orders. Only shown if "group products on orders" is enabledimages list
The images associated with this productCreate a product
Example request with curl
curl -X POST https://api.orderspace.com/v1/products \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "product": { "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "sku": "AD01-RED-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "sku": "AD01-RED-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "sku": "AD01-RED-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ {"id": "ca_x61lk8j7"}, {"id": "ca_3xwy7mwo"} ], "grouping_category_id": "ca_x61lk8j7" } }'
Example success response [HTTP 200 Success]
{ "product": { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7", "images": [] } }
Example error response [HTTP 422 Unprocessable Entity]
{ "message": "Validation failed: Product Code must be unique" }
Create a new product
HTTP Request
POST https://api.orderspace.com/v1/products
Response
HTTP 200 Success
- The product object in JSON formatHTTP 422 Unprocessable Entity
- A message describing the errorsList products
Example request with curl
curl -X GET https://api.orderspace.com/v1/products \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -d limit=20 \ -d starting_after=pr_njgnve1o
Example success response [HTTP 200 Success]
{ "products": [ { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7", "images": [ "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/image_name-8vr0j3wd.jpg", "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/another_image_name-eorkg2nv.png" ] }, {...}, {...} ], "has_more": true }
Retrieve a list of products. Products are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/products
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last product in the list will retrieve the next page of products -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
updated_since optional
Return records updated since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
code optional
Return products with the specified code. Should only return a single product as the codes are unique -
name optional
Return products with the specified name -
active optional
Return products with active set to the specified value, one oftrue
orfalse
-
category_id optional
Return products in the specified category
Response
HTTP 200 Success
- A list of products in JSON formatRetrieve a product
Example request with curl
curl -X GET https://api.orderspace.com/v1/products/pr_lj3pwm1n \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "product": { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7", "images": [ "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/image_name-8vr0j3wd.jpg", "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/another_image_name-eorkg2nv.png" ] } }
Retrieve a single product by ID
HTTP Request
GET https://api.orderspace.com/v1/products/:product_id
Response
HTTP 200 Success
- The product record in JSON formatHTTP 404 Not Found
- A message describing the errorUpdate a product
Example request with curl
curl -X PUT https://api.orderspace.com/v1/products/pr_lj3pwm1n \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "product": { "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-RED-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0}, {"id": "pl_zyjgq19r", "unit_price": null} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-RED-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-RED-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ {"id": "ca_x61lk8j7"}, {"id": "ca_3xwy7mwo"} ], "grouping_category_id": "ca_x61lk8j7" } }'
Example success response [HTTP 200 Success]
{ "product": { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7", "images": [ "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/image_name-8vr0j3wd.jpg", "https://a1b2c3d4ef.cloudfront.net/accountname/images/products/another_image_name-eorkg2nv.png" ] } }
Example error response [HTTP 422 Unprocessable Entity]
{ "message": "Validation failed: Product Code must be unique" }
Update an existing product. We recommend that you include all the fields and all the product variants in your update, not just the ones that are changing. Existing product variants should include their ID which can be obtained by retrieving the product through the API first.
HTTP Request
PUT https://api.orderspace.com/v1/products/:product_id
Response
HTTP 200 Success
- The product object in JSON formatHTTP 422 Unprocessable Entity
- A message describing the errorsInventory Levels
An inventory level represents the quantity in stock and quantity available to order for a product variant. The endpoints for this resource allow stock levels to be retrieved and updated in bulk. For more details on how inventory works in Orderspace and the difference between on hand and available, see our help docs at https://docs.orderspace.com/article/48-about-inventory
The Inventory Level Object
Example inventory level
{ "inventory_level": { "sku": "AA-RED-XS", "on_hand": 5, "available": 5 } }
-
sku string
Inventory levels use the SKU rather than an ID as a reference to a specific product variant -
on_hand number
On hand represents the quantity in physically in stock -
available number
Available represents the quantity available for customers to order
List inventory levels
Example request with curl
curl -X GET https://api.orderspace.com/v1/inventory_levels \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -d limit=20 \ -d starting_after=AD-08
Example success response [HTTP 200 Success]
{ "inventory_levels": [ { "sku": "AD-10", "on_hand": 10, "available": 4 }, { "sku": "AD-12", "on_hand": 45, "available": 45 }, { "sku": "AD-14", "on_hand": 0, "available": 0 } ], "has_more": false }
Retrieve a list of inventory levels. Inventory levels are returned in SKU order
HTTP Request
GET https://api.orderspace.com/v1/inventory_levels
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the SKU of the last inventory level in the list will retrieve the next page of inventory levels -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
updated_since optional
Return inventory levels updated since the given date and time in ISO 8601 format, e.g.2019-10-29T21:00
-
product_id optional
Return inventory levels for a specific product -
sku optional
Return the inventory level for a specific SKU
Update inventory levels
Example request with curl
curl -X POST https://api.orderspace.com/v1/inventory_levels \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "inventory_levels": [ { "sku": "11106-WB-10", "on_hand": 30 }, { "sku": "11106-WB-12", "on_hand": 45 }, { "sku": "11106-WB-14", "on_hand": 20 } ] }'
Example success response [HTTP 200 Success]
{ "inventory_levels": [ { "sku": "11106-WB-10", "on_hand": 30, "available": 20 }, { "sku": "11106-WB-12", "on_hand": 45, "available": 45 }, { "sku": "11106-WB-14", "on_hand": 20, "available": 0 } ] }
Example error response [HTTP 422 Unprocessable Entity]
{ "message": "On Hand and Available can not be updated at the same time because one is automatically calculated from the other" }
Update the specified inventory levels. Unlike most update requests, multiple inventory levels can be updated at once, up to a maximum of 200 per request.
Update will accept either
on_hand
oravailable
, but not both at the same time because one is calculated from the other. For example, ifon_hand
is increased from 10 to 15,available
will be automatically increased by 5.See our help docs at https://docs.orderspace.com/article/48-about-inventory for more details on the difference between On Hand and Available.
HTTP Request
POST https://api.orderspace.com/v1/inventory_levels
Response
HTTP 200 Success
- A list of updated inventory levels in JSON formatHTTP 422 Unprocessable Entity
- A message describing the errorsInvoices
The Invoice object
Example invoice
{ "invoice": { "id": "iv_7xg471xv", "number": "INV-1288", "invoice_date": "2021-04-24", "customer_id": "cu_pg34zo1x", "company_name": "BP Twelve", "email_address": "bp12@alliumstudios.com", "orders": [ { "id": "or_e875r5l5", "number": 1288 } ], "payment_terms": "15 Days", "due_date": "2021-05-09", "paid": true, "proforma": false, "deposit": { "percentage": 25.0, "due_date": "2021-04-24" }, "comments": "", "address": { "company_name": "BP Twelve", "contact_name": "", "line1": "addr1", "line2": "", "city": "", "state": "", "postal_code": "NN14", "country": "GB" }, "invoice_lines": [ { "sku": "ZAG-D-16", "name": "Angelica Dress", "options": "Size: 16", "quantity": 1, "unit_price": 22.25, "sub_total": 22.25, "tax_rate": 20.0, "tax_amount": 4.45, "order_line_id": "ol_d16560mn" } ], "currency": "GBP", "net_total": 22.25, "gross_total": 26.7, "payments": [ { "amount": 26.7, "payment_date": "2021-04-24", "source": "card", "description": "Visa ending 3220", "reference": "pi_1IjW8KJzxI5C4d4qXkHyOFKZ" } ] } }
-
id string
Unique auto-generated identifier for the invoice -
number string
Unique number identifying the invoice, shown to the customer. Can contain a prefix made of both letters and numbers -
invoice_date string
The date the invoice was issued in ISO 8601 format -
customer_id string
Internal identifier for the related customer resource -
company_name string
The customer's company name -
email_address string
The customer's email address for invoices. Multiple email addresses may be present, separated by commas -
orders list
A list of orders associated with this invoice. Invoices are generated from orders and the items on an invoice correspond directly to items on the associated ordersChild Attributes of orders
-
order.id string
Unique auto-generated identifier for the order -
order.number number
Unique number identifying the order, shown to the customer
-
-
payment_terms string
A string representation of the payment terms offered on this invoice -
due_date string
The date payment is due in ISO 8601 format -
paid boolean
Set totrue
if the invoice has been paid in full -
proforma boolean
Set totrue
if this is a proforma invoice -
comments string
Comments to be shown on the invoice -
address hash
The customer's billing addressChild Attributes
-
address.company_name string
Company name -
address.contact_name string
Contact name -
address.line1 string
Address line 1 -
address.line2 string
Address line 2 -
address.city string
City, town or village -
address.state string
State, county, province or region. U.S., Canadian and Australian addresses should use the abbreviated form of the state -
address.postal_code string
ZIP or postal code -
address.country string
Two-letter ISO 3166-1 country code
-
-
invoice_lines list
List of the individual lines that make up the invoice asinvoice lines
Child Attributes of Invoice Lines
-
invoice_line.sku string
The unique code for the item -
invoice_line.name string
The name of the item -
invoice_line.options string
The options (size/color etc) of the item -
invoice_line.quantity number
The number of items ordered -
invoice_line.unit_price number
The unit price of each item on this line -
invoice_line.sub_total number
The line sub-total excluding tax -
invoice_line.tax_rate number
The tax rate applied to this line as a percentage -
invoice_line.tax_amount number
The total tax applied to this line -
invoice_line.order_line_id string
The ID of the order line associated with this line
-
-
currency string
The three-letter ISO currency code representing the invoice's currency -
net_total number
The total cost of all items on the invoice excluding tax -
gross_total number
The total cost of all items on the invoice including tax -
payments list
A list of payments made against this invoiceChild Attributes of Payments
-
payment.amount number
The amount paid in the invoice's currency -
payment.payment_date string
The date the payment was made in ISO 8601 format -
payment.source string
The name of the payment source -
payment.description string
A description of the payment -
payment.reference string
A reference for the payment provided by the payment gateway
-
List invoices
Example request with curl
curl -X GET https://api.orderspace.com/v1/invoices \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -d limit=20 \ -d starting_after=iv_dmqjl0x8
Example success response [HTTP 200 Success]
{ "invoices": [ { "id": "iv_7xg471xv", "number": "INV-1288", "invoice_date": "2021-04-24", "customer_id": "cu_pg34zo1x", "company_name": "BP Twelve", "email_address": "bp12@alliumstudios.com", "orders": [ { "id": "or_e875r5l5", "number": 1288 } ], "payment_terms": "15 Days", "due_date": "2021-05-09", "paid": true, "proforma": false, "deposit": { "percentage": 25.0, "due_date": "2021-04-24" }, "comments": "", "address": { "company_name": "BP Twelve", "contact_name": "", "line1": "addr1", "line2": "", "city": "", "state": "", "postal_code": "NN14", "country": "GB" }, "invoice_lines": [ { "sku": "ZAG-D-16", "name": "Angelica Dress", "options": "Size: 16", "quantity": 1, "unit_price": 22.25, "sub_total": 22.25, "tax_rate": 20.0, "tax_amount": 4.45, "order_line_id": "ol_d16560mn" } ], "currency": "GBP", "net_total": 22.25, "gross_total": 26.7, "payments": [ { "amount": 26.7, "payment_date": "2021-04-24", "source": "card", "description": "Visa ending 3220", "reference": "pi_1IjW8KJzxI5C4d4qXkHyOFKZ" } ] }, {...}, {...} ] }
Retrieve a list of invoices. Invoices are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/invoices
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last invoice in the list will retrieve the next page of invoices -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
created_since optional
Return records created since the given date and time in ISO 8601 format, e.g.2021-10-29T21:00
-
invoice_date_after optional
Return invoices with an invoice date after the given date in ISO 8601 format, e.g.2019-10-29
-
invoice_date_before optional
Return invoices with an invoice date before the given date in ISO 8601 format, e.g.2021-10-29
-
due_date_after optional
Return invoices with a due date after the given date in ISO 8601 format, e.g.2019-10-29
-
due_date_before optional
Return invoices with a due date before the given date in ISO 8601 format, e.g.2021-10-29
-
number optional
Return an invoice with the corresponding number -
customer_id optional
Return invoices for a specific customer -
paid optional
Return invoices with a matching paid value. Set to either true or false -
proforma optional
Return invoices with a matching proforma value. Set to either true or false
Response
HTTP 200 Success
- A list of invoices in JSON formatRetrieve an invoice
Example request with curl
curl -X GET https://api.orderspace.com/v1/invoices/iv_7xg471xv \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "invoice": { "id": "iv_7xg471xv", "number": "INV-1288", "invoice_date": "2021-04-24", "customer_id": "cu_pg34zo1x", "company_name": "BP Twelve", "email_address": "bp12@alliumstudios.com", "orders": [ { "id": "or_e875r5l5", "number": 1288 } ], "payment_terms": "15 Days", "due_date": "2021-05-09", "paid": true, "proforma": false, "deposit": { "percentage": 25.0, "due_date": "2021-04-24" }, "comments": "", "address": { "company_name": "BP Twelve", "contact_name": "", "line1": "addr1", "line2": "", "city": "", "state": "", "postal_code": "NN14", "country": "GB" }, "invoice_lines": [ { "sku": "ZAG-D-16", "name": "Angelica Dress", "options": "Size: 16", "quantity": 1, "unit_price": 22.25, "sub_total": 22.25, "tax_rate": 20.0, "tax_amount": 4.45, "order_line_id": "ol_d16560mn" } ], "currency": "GBP", "net_total": 22.25, "gross_total": 26.7, "payments": [ { "amount": 26.7, "payment_date": "2021-04-24", "source": "card", "description": "Visa ending 3220", "reference": "pi_1IjW8KJzxI5C4d4qXkHyOFKZ" } ] } }
Retrieve a single invoice by ID
HTTP Request
GET https://api.orderspace.com/v1/invoices/:invoice_id
Response
HTTP 200 Success
- The invoice record in JSON formatHTTP 404 Not Found
- A message describing the errorCategories
Categories are used to group related products together
The Category object
Example category
{ "category": { "id": "ca_n51qpxjd", "name": "Dresses", "description": "", "active": true, "parent_id": null } }
-
id string
Unique auto-generated identifier for the category -
name string
The name of the categorydescription string
Text shown on the category page. Can contain HTML tags for formattingactive boolean
Controls whether the categories is visible on the ordering siteparent_id string
The identifier of the parent category if this category is a sub-categoryList categories
Example request with curl
curl https://api.orderspace.com/v1/categories \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -d limit=20 \ -d starting_after=ca_57w9p7jz
Example HTTP 200 success response
{ "categories": [ { "id": "ca_n51qpxjd", "name": "Dresses", "description": "", "active": true, "parent_id": null }, {...}, {...} ], "has_more": true }
Retrieve a list of categories. Categories are returned based on their sort order on the web site
HTTP Request
GET https://api.orderspace.com/v1/categories
Parameters
-
starting_after optional
A cursor used for pagination. Setting `starting_after` to the ID of the last category in the list will retrieve the next page of categories -
limit optional
A limit on the number of records returned. The default is 50 and the maximum limit is 200 -
name optional
Return categories matching this name -
parent_id optional
Return sub-categories with this parent
Response
HTTP 200 Success
- A list of categories in JSON formatCustomer Groups
Customer groups represent a set of customers with shared settings. Each customer can belong to a single customer group
The Customer Group object
Example customer group
{ "customer_group": { "id": "cg_mg5r89wo", "name": "Default" } }
-
id string
Unique auto-generated identifier for the customer group -
name string
A unique name for the customer groupList customer groups
Example request with curl
curl "https://api.orderspace.com/v1/customer_groups" \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "customer_groups": [ { "id": "cg_mg5r89wo", "name": "Default" }, {...}, {...} ] }
Retrieve a list of customer groups. This endpoint does not support pagination
HTTP Request
GET https://api.orderspace.com/v1/customer_groups
Response
HTTP 200 Success
- A list of customer groups in JSON formatPrice Lists
Price lists are used to charge different prices to different customers. Each price list has a currency, so they can also be used to support multi-currency ordering
The Price List object
Example price list
{ "price_list": { "id": "pr_z0j7yjl2", "name": "Euros", "currency": "EUR", "conversion_rate": 100 } }
-
id string
Unique auto-generated identifier for the price list -
name string
A unique name for the price listcurrency string
The three-letter ISO currency code representing the price list's currencyconversion_rate number
The conversion rate, as a percentage, applied to item prices if they don't have a specific price set for this price listList price lists
Example request with curl
curl "https://api.orderspace.com/v1/price_lists" \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "price_lists": [ { "id": "pr_z0j7yjl2", "name": "Euros", "currency": "EUR", "conversion_rate": 100 }, {...}, {...} ] }
Retrieve a list of price lists. This endpoint does not support pagination
HTTP Request
GET https://api.orderspace.com/v1/price_lists
Response
HTTP 200 Success
- A list of price lists in JSON formatPayment Terms
Payment Terms represent the terms of payment offered on invoices. Each customer has one set of payment terms assigned to them which are used as the default payment terms for new invoices but specific terms can also be assigned to an invoice when it is created
The Payment Terms object
Example payment terms
{ "payment_terms": { "id": "pr_z0j7yjl2", "name": "30 Days", "days_due": 30, "deposit_pecentage": 0.0, "deposit_days_due": 0 } }
-
id string
Unique auto-generated identifier for the payment terms -
name string
A unique name for the payment termsdays_due number
The number of days after the invoice date that payment is due. Set to zero for immediate paymentdeposit_percentage number
The percentage of the invoice total that is required to be paid as a deposit. Set to zero for no depositdeposit_days_due number
The number of days after the invoice date that the deposit s due. Set to zero for immediate paymentList payment terms
Example request with curl
curl "https://api.orderspace.com/v1/payment_terms" \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "payment_terms": [ { "id": "pr_z0j7yjl2", "name": "30 Days", "days_due": 30, "deposit_pecentage": 0.0, "deposit_days_due": 0 }, {...}, {...} ] }
Retrieve a list of payment terms. This endpoint does not support pagination
HTTP Request
GET https://api.orderspace.com/v1/payment_terms
Response
HTTP 200 Success
- A list of payment terms in JSON formatTax Rates
Tax Rates represent the different rates of tax that can be charged on items
The Tax Rate object
Example tax rate
{ "tax_rate": { "id": "tr_xk7pe5kd", "name": "Standard", "rate": 20.0 } }
-
id string
Unique auto-generated identifier for the tax rate -
name string
A unique name for the tax raterate number
The tax rate as a percentageList tax rates
Example request with curl
curl "https://api.orderspace.com/v1/tax_rates" \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "tax_rates": [ { "id": "tr_xk7pe5kd", "name": "Standard", "rate": 20.0 }, {...}, {...} ] }
Retrieve a list of tax rates. This endpoint does not support pagination
HTTP Request
GET https://api.orderspace.com/v1/tax_rates
Response
HTTP 200 Success
- A list of tax rates in JSON formatPreorder Windows
Preorder Windows represent a specific season or drop that customers are buying for. In Orderspace you can take orders for multiple preorder windows and also sell from stock on the same items at the same time. Preorders allow you to take forward orders on items that have not yet been made. Preordered items are held back and do not reduce stock levels or appear in the Dispatch area for fulfilment until they are released.
The Preorder Window object
Example preorder window
{ "preorder_window": { "id": "pw_y1pj71pk", "name": "Spring/Summer 2021", "deadline": "2021-05-21", "due": "2021-06-01", "categories": [ { "id": "ca_kj6mz919", "name": "Spring/Summer 2021" } ] } }
-
id string
Unique auto-generated identifier for the preorder window -
name string
A short name describing the preorder window such as Spring/Summer 2021 or SS21 Drop 1deadline string
The deadline date for this preorder window in ISO 8601 format. This will be shown to customers and preordering will automatically stop after this daydue string
The due date for this preorder window in ISO 8601 format. This will be shown to customers to inform them when the preordered items are due to arrive. Shown for information onlycategories list
The categories associated with this preorder window. Products in the selected categories will become preorderable in this preorder windowChild Attributes of Categories
-
id string
Unique auto-generated identifier for the category -
name string
The name of the category
List preorder windows
Example request with curl
curl "https://api.orderspace.com/v1/preorder_windows" \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "preorder_windows": [ { "id": "pw_y1pj71pk", "name": "Spring/Summer 2021", "deadline": "2021-05-21", "due": "2021-06-01", "categories": [ { "id": "ca_kj6mz919", "name": "Spring/Summer 2021" } ] }, {...}, {...} ] }
Retrieve a list of preorder windows. This endpoint does not support pagination
HTTP Request
GET https://api.orderspace.com/v1/preorder_windows
Response
HTTP 200 Success
- A list of preorder windows in JSON formatWebhooks
A webhook represents a subscription to one or more events. This allows you to be informed in near real-time when something happens in Orderspace without the need for polling. When an event occurs, Orderspace will send an
HTTP POST
request inJSON
format to the webhook's endpoint.Webhooks are created, updated and deleted through the API.
The Webhook object
Example webhook
{ "webhook": { "id":"wh_1q4qn43v", "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events":["order.created", "dispatch.created"], "signing_key":"UNxdW7ugYl8PCKjVGkoXkHARkCoFT3eXpdpDsF1s" } }
-
id string
Unique auto-generated identifier for the webhook -
endpoint string
An HTTPS URL on your server where Orderspace will send events. The endpoint should accept HTTP POST requests in JSON formatevents list
A list of events that the webhook is subscribed to. Valid events are "customer.created", "customer.updated", "customer.deleted", "dispatch.created", "inventory_level.updated", "invoice.created", "invoice.deleted", "payment.created", "product.created", "product.updated", "product.deleted", "order.created", "order.updated" and "order.deleted"signing_key string
An auto-generated key used to sign the payload of each request to verify that it came from Orderspace. See Webhook Events Validation for more details.Create a webhook
Example request with curl
curl -X POST https://api.orderspace.com/v1/webhooks \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "webhook": { "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["order.created", "dispatch.created"] } }'
Example success response [HTTP 200 Success]
{ "webhook": { "id": "wh_nq479yz6", "endpoint": "https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["order.created","dispatch.created"], "signing_key": "7R2gNdE4GU8K06WXPV9lOXBic9mSs5LjKMsk46eW" } }
Example error response [HTTP 422 Unprocessable Entity]
{ "message": "Validation failed: Endpoint can't be blank, Endpoint must be a https url" }
Create a new webhook, subscribing the specified endpoint to a list of events.
Note that the
signing_key
is generated by Orderspace and should be stored for use in validating events.HTTP Request
POST https://api.orderspace.com/v1/webhooks
Response
HTTP 200 Success
- The webhook object in JSON formatHTTP 422 Unprocessable Entity
- A message describing the errorsList webhooks
Example request with curl
curl -X GET https://api.orderspace.com/v1/webhooks \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "webhooks": [ { "id": "wh_o9ernm4p", "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["order.created", "dispatch.created"], "signing_key":"UNxdW7ugYl8PCKjVGkoXkHARkCoFT3eXpdpDsF1s" }, {...}, {...} ] }
Retrieve a list of webhooks. Webhooks are returned in the order they are created with the most recently created listed first
HTTP Request
GET https://api.orderspace.com/v1/webhooks
Response
HTTP 200 Success
- A list of webhooks in JSON formatRetrieve a webhook
Example request with curl
curl -X GET https://api.orderspace.com/v1/webhooks/wh_o9ernm4p \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "webhook": { "id": "wh_o9ernm4p", "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["order.created", "dispatch.created"], "signing_key":"UNxdW7ugYl8PCKjVGkoXkHARkCoFT3eXpdpDsF1s" } }
Retrieve a single webhook by ID
HTTP Request
GET https://api.orderspace.com/v1/webhooks/:webhook_id
Response
HTTP 200 Success
- The webhook in JSON formatHTTP 404 Success
- A message describing the errorUpdate a webhook
Example request with curl
curl -X PUT https://api.orderspace.com/v1/webhooks/wh_o9ernm4p \ -H "Authorization: Bearer {ACCESS TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "webhook": { "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["invoice.created"] } }'
Example success response [HTTP 200 Success]
{ "webhook": { "id": "wh_o9ernm4p", "endpoint":"https://webhook.site/6e3931ec-9f4b-4b3a-932f-42f73d1dc45f", "events": ["invoice.created"], "signing_key":"UNxdW7ugYl8PCKjVGkoXkHARkCoFT3eXpdpDsF1s" } }
Update an existing webhook to change the endpoint or list of subscribed events
HTTP Request
GET https://api.orderspace.com/v1/webhooks/:webhook_id
Response
HTTP 200 Success
- The webhook in JSON formatHTTP 404 Success
- A message describing the errorDelete a webhook
Example request with curl
curl -X DELETE https://api.orderspace.com/v1/webhooks/wh_o9ernm4p \ -H "Authorization: Bearer {ACCESS TOKEN}"
Example success response [HTTP 200 Success]
{ "webhook": { "id": "wh_o9ernm4p", "deleted": true } }
Delete a webhook. Orderspace will stop sending events to the endpoint
HTTP Request
DELETE https://api.orderspace.com/v1/webhooks/:webhook_id
Response
HTTP 200 Success
- A short representation of the webhook in JSON formatHTTP 404 Success
- A message describing the errorWebhook Events
This section documents the events sent to webhook endpoints. Use the Webhooks resource to create and manage event subscriptions.
Expected Response
Events are sent as an
HTTP POST
request to your endpoint when they occur in Orderspace.An
HTTP 200 Success
response should be returned. If any other response is received, Orderspace will retry the request with an incremental backoff. After multiple failed attempts your webhook will be disabled.Validation
Calculating the request signature in Ruby
Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', signing_key, request_payload))
Calculating the request signature in NodeJS
var crypto = require('crypto'); crypto.createHmac('sha256', signing_key).update(request_payload).digest("base64");
Every request sent to your endpoint is signed with an
X-Orderspace-Signature
HTTP header. To calculate the signature, the request payload is hashed using HMACSHA256 with the webhooksigning_key
, and then base64 encoded.To validate that the request came from Orderspace, calculate the signature using the request payload and the stored
signing_key
and compare it to the one in the request header.Request Format
The payload of a request is a list of events in
JSON
format. A request will often contain a single event, but to reduce network traffic multiple events may be sent together. This is more likely on a bulk action such as a stock update. A single request can contain up to 50 events. Each event in the list is self-contained and events of different event types could be mixed together in the same request. Examples of each event type are shown below.customer.created
Example customer.created webhook request
[ { "event": "customer.created", "data": { "customer": { "id": "cu_dnwz8gnx", "company_name": "Blue Sky", "created_at": "2021-03-09T13:08:51Z", "status": "active", "reference": "", "buyers": [ { "name": "Emilia Jane Dogherty", "email_address": "sample@orderspace.com" } ], "phone": "12345", "email_addresses": { "orders": "sample@orderspace.com", "dispatches": "sample@orderspace.com", "invoices": "sample@orderspace.com", }, "tax_number": "", "tax_rate_id": null, "addresses": [ { "company_name": "Blue Sky", "contact_name": "Emilia Jane Dogherty", "line1": "12 Blue Sky Lane", "line2": "", "city": "Bristol", "postal_code": "BS1 2DF", "state": "", "country": "GB" } ], "minimum_spend": 150.0, "payment_terms_id": "pt_zkmqv8e0", "customer_group_id": "cg_w2n6ln8v", "price_list_id": "pr_3715yj58" } } }, {...}, {...} ]
Triggered when a customer is created.
data
contains the customer record.customer.deleted
Example customer.deleted webhook request
[ { "event": "customer.deleted", "data": { "customer": { "id": "cu_dnwz8gnx", "company_name": "Blue Sky", "deleted": true } } }, {...}, {...} ]
Triggered when a customer is deleted.
data
contains fields to identify the customer.customer.updated
Example customer.updated webhook request
[ { "event": "customer.updated", "data": { "customer": { "id": "cu_dnwz8gnx", "company_name": "Blue Sky", "created_at": "2021-03-09T13:08:51Z", "status": "active", "reference": "", "buyers": [ { "name": "Emilia Jane Dogherty", "email_address": "sample@orderspace.com" } ], "phone": "12345", "email_addresses": { "orders": "sample@orderspace.com", "dispatches": "sample@orderspace.com", "invoices": "sample@orderspace.com", }, "tax_number": "", "tax_rate_id": null, "addresses": [ { "company_name": "Blue Sky", "contact_name": "Emilia Jane Dogherty", "line1": "12 Blue Sky Lane", "line2": "", "city": "Bristol", "postal_code": "BS1 2DF", "state": "", "country": "GB" } ], "minimum_spend": 150.0, "payment_terms_id": "pt_zkmqv8e0", "customer_group_id": "cg_w2n6ln8v", "price_list_id": "pr_3715yj58" } } }, {...}, {...} ]
Triggered when a customer is updated.
data
contains the customer record with the updates applied.dispatch.created
Example dispatch.created webhook request
[ { "event": "dispatch.created", "data": { "dispatch": { "id": "di_4kzzxdk2", "order_id": "or_wlvzog4g", "order_number": 1289, "created": "2021-04-16T12:58:39Z", "comments": "Sent by Royal Mail using Next Day Delivery", "customer_note": "", "customer_po_number": "", "shipping_type": "Next Day Delivery", "shipping_address": { "company_name": "Blue Sky", "contact_name": "Emilia Jane Dogherty", "line1": "12 Blue Sky Lane", "line2": "", "city": "Bristol", "state": "", "postal_code": "BS1 2DF", "country": "GB" }, "email_address": "sample@orderspace.com", "phone": "12345", "dispatch_lines": [ { "order_line_id": "ol_z1ow2pdm", "sku": "ZAG-D-16", "name": "Angelica Dress", "options": "Size: 16", "quantity": 1 }, { "order_line_id": "ol_nm427o01", "sku": "ZAG-D-18", "name": "Angelica Dress", "options": "Size: 18", "quantity": 2 }, { "order_line_id": "ol_pmvznz21", "sku": "ZAG-D-20", "name": "Angelica Dress", "options": "Size: 20", "quantity": 3 }, ] } } }, {...}, {...} ]
Triggered when items on an order are dispatched.
data
contains the dispatch record.inventory_level.updated
Example inventory_level.updated webhook request
[ { "event": "inventory_level.updated", "data": { "inventory_level": { "sku": "AD01-10", "on_hand": 20.0, "on_hand_adjustment": 10.0, "available": 20.0, "available_adjustment": 10.0 } } }, {...}, {...} ]
Triggered when an inventory level is updated.
If multiple inventory levels are changed in a bulk update there will be a separate event for each item, but multiple events may be sent in the same request.
data
contains the inventory level update record.invoice.created
Example invoice.created webhook request
[ { "event": "invoice.created", "data": { "invoice": { "id": "iv_7xg471xv", "number": "INV-1288", "invoice_date": "2021-04-24", "customer_id": "cu_pg34zo1x", "company_name": "BP Twelve", "email_address": "bp12@alliumstudios.com", "orders": [ { "id": "or_e875r5l5", "number": 1288 } ], "payment_terms": "15 Days", "due_date": "2021-05-09", "paid": true, "proforma": false, "deposit": { "percentage": 25.0, "due_date": "2021-04-24" }, "comments": "", "address": { "company_name": "BP Twelve", "contact_name": "", "line1": "addr1", "line2": "", "city": "", "state": "", "postal_code": "NN14", "country": "GB" }, "invoice_lines": [ { "sku": "ZAG-D-16", "name": "Angelica Dress", "options": "Size: 16", "quantity": 1, "unit_price": 22.25, "sub_total": 22.25, "tax_rate": 20.0, "tax_amount": 4.45 } ], "currency": "GBP", "net_total": 22.25, "gross_total": 26.7, "payments": [ { "amount": 26.7, "payment_date": "2021-04-24", "source": "card", "description": "Visa ending 3220", "reference": "pi_1IjW8KJzxI5C4d4qXkHyOFKZ" } ] } } }, {...}, {...} ]
Triggered when an invoice is created.
data
contains the invoice record.invoice.deleted
Example invoice.deleted webhook request
[ { "event": "invoice.deleted", "data": { "invoice": { "id": "iv_7xg471xv", "number": "INV-1288", "deleted": true } } }, {...}, {...} ]
Triggered when an invoice is deleted.
data
contains fields use to identify the invoice.payment.created
Example payment.created webhook request
[ { "event": "payment.created", "data": { "payment": { "invoice_id": "iv_7xg471xv", "invoice_number": "INV-1288", "amount": 26.7, "payment_date": "2021-04-24", "source": "card", "description": "Visa ending 3220", "reference": "pi_1IjW8KJzxI5C4d4qXkHyOFKZ" } } }, {...}, {...} ]
Triggered when a payment is made or recorded on an invoice.
data
contains the payment record.product.created
Example product.created webhook request
[ { "event": "product.created", "data": { "product":{ "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7" } } }, {...}, {...} ]
Triggered when a product is created.
data
contains the product record.product.deleted
Example product.deleted webhook request
[ { "event": "product.deleted", "data": { "product": { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "deleted": true } } }, {...}, {...} ]
Triggered when a product is deleted.
data
contains fields used to identify the product.product.updated
Example product.updated webhook request
[ { "event": "product.updated", "data": { "product": { "id": "pr_lj3pwm1n", "code": "AD01", "name": "Alexa Dress", "description": "Summer colours, fully lined", "active": true, "tariff_code": "0804.401", "country_of_origin": "India", "composition": "100% cotton", "variant_options": ["Color", "Size"], "product_variants": [ { "id": "pv_v18kxq1e", "sku": "AD01-10", "barcode": "123456789", "options": {"Color": "Red", "Size": "10"}, "unit_price": 32.0, "price_list_prices": [ {"id": "pr_z0j7yjl2", "unit_price": 35.0} ], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": 3, "weight": 0.0, }, { "id": "pv_xjz5xvjk", "sku": "AD01-12", "barcode": "1123456789", "options": {"Color": "Red", "Size": "12"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 2, "multiple": 2, "weight": 0.0, }, { "id": "pv_q1l2n634", "sku": "AD01-14", "barcode": "2123456789", "options": {"Color": "Red", "Size": "14"}, "unit_price": 32.0, "price_list_prices": [], "rrp": 72.0, "backorder": true, "minimum": 4, "multiple": null, "weight": 1.0, } ], "categories": [ { "id": "ca_x61lk8j7", "name": "Dresses" }, { "id": "ca_3xwy7mwo", "name": "Spring / Summer 2022" } ], "grouping_category_id": "ca_x61lk8j7" } } }, {...}, {...} ]
Triggered when a product is updated.
data
contains the product record with the updates applied.order.created
Example order.created webhook request
[ { "event": "order.created", "data": { "order": { "id": "or_l5DYqeDn", "number": 1204, "created": "2020-04-08T15:03:55Z", "status": "new", "customer_id": "cu_gpbOljAn" "company_name": "Sample Customer", "phone": "07911 123456", "email_addresses": { "orders": "sample@orderspace.com", "dispatches": "sample@orderspace.com", "invoices": "sample@orderspace.com", } "delivery_date": "2020-04-09", "reference": "", "internal_note": "", "customer_po_number": "", "customer_note": "", "standing_order_id": "or_68ogydlx", "shipping_type": "Special Delivery", "shipping_address": { "company_name": "Sample Customer", "contact_name": "", "line1": "34 Edgar Buildings", "line2": "George Street", "city": "Bath", "state": "", "postal_code": "BA1 2FJ", "country": "GB" }, "billing_address": { "company_name": "Sample Customer", "contact_name": "", "line1": "336 Hargrave Rd", "line2": "Windsor", "city": "New York", "state": "NY", "postal_code": "13865", "country": "US" }, "order_lines": [ { "id": "ol_NdOLvlpw", "sku": "AM-D-CHR-10", "name": "Amelia Dress", "options": "Colour: Charcoal, Size: 10", "grouping_category": { "id": "ca_9n1klwr5", "name": "Dresses" }, "shipping": false, "quantity": 10, "unit_price": 30.0, "sub_total": 300.0, "tax_name": "Standard", "tax_rate": 20.0, "tax_amount": 60.0, "on_hold": false, "invoiced": 0, "paid": 0, "dispatched": 0 } ], "currency": "GBP", "net_total": 306.1, "gross_total": 366.1 } } }, {...}, {...} ]
Triggered when an order is created.
data
contains the order record.order.deleted
Example order.deleted webhook request
[ { "event": "order.deleted", "data": { "order": { "id": "or_l5DYqeDn", "number": 1204, "deleted": true } } }, {...}, {...} ]
Triggered when an order is deleted.
data
contains fields used to identify the order.order.updated
Example order.updated webhook request
[ { "event": "order.updated", "data": { "order": { "id": "or_l5DYqeDn", "number": 1204, "created": "2020-04-08T15:03:55Z", "status": "new", "customer_id": "cu_gpbOljAn" "company_name": "Sample Customer", "phone": "07911 123456", "email_addresses": { "orders": "sample@orderspace.com", "dispatches": "sample@orderspace.com", "invoices": "sample@orderspace.com", } "delivery_date": "2020-04-09", "reference": "", "internal_note": "", "customer_po_number": "", "customer_note": "", "standing_order_id": "or_68ogydlx", "shipping_type": "Special Delivery", "shipping_address": { "company_name": "Sample Customer", "contact_name": "", "line1": "34 Edgar Buildings", "line2": "George Street", "city": "Bath", "state": "", "postal_code": "BA1 2FJ", "country": "GB" }, "billing_address": { "company_name": "Sample Customer", "contact_name": "", "line1": "336 Hargrave Rd", "line2": "Windsor", "city": "New York", "state": "NY", "postal_code": "13865", "country": "US" }, "order_lines": [ { "id": "ol_NdOLvlpw", "sku": "AM-D-CHR-10", "name": "Amelia Dress", "options": "Colour: Charcoal, Size: 10", "grouping_category": { "id": "ca_9n1klwr5", "name": "Dresses" }, "shipping": false, "quantity": 10, "unit_price": 30.0, "sub_total": 300.0, "tax_name": "Standard", "tax_rate": 20.0, "tax_amount": 60.0, "on_hold": false, "invoiced": 0, "paid": 0, "dispatched": 0 } ], "currency": "GBP", "net_total": 306.1, "gross_total": 366.1 } } }, {...}, {...} ]
Triggered when an order is updated.
data
contains the order record with the updates applied.
-
-