NAV

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:

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.

CodeDescription
400 Bad RequestThe request was unacceptable, often due to malformed JSON input or missing required parameters
401 UnauthorizedThe access token was invalid or missing
404 Not FoundThe requested endpoint or resource was not found
422 Unprocessable EntityThe request could not be processed due to errors, for example validation errors when creating or updating a resource
429 Too Many RequestsSee the section on throttling
500 Internal Server ErrorSomething 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"
  }
}

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

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
  }
}

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

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
      },
    ]   
  }
}

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

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"
    ]
  }
}

Create 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 format

HTTP 422 Unprocessable Entity - A message describing the errors

List 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

Response

HTTP 200 Success - A list of products in JSON format

Retrieve 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 format

HTTP 404 Not Found - A message describing the error

Update 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 format

HTTP 422 Unprocessable Entity - A message describing the errors

Inventory 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
  }
}

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

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 or available, but not both at the same time because one is calculated from the other. For example, if on_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 format

HTTP 422 Unprocessable Entity - A message describing the errors

Invoices

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"
      }
    ]
  }
}

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

Response

HTTP 200 Success - A list of invoices in JSON format

Retrieve 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 format

HTTP 404 Not Found - A message describing the error

Categories

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
  }
}

List 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

Response

HTTP 200 Success - A list of categories in JSON format

Customer 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"
  }
}

List 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 format

Price 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
  }
}

List 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 format

Payment 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
  }
}

List 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 format

Tax 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
  }
}

List 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 format

Preorder 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" }
    ]
  }
}

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 format

Webhooks

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 in JSON 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"
  }
}

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 format

HTTP 422 Unprocessable Entity - A message describing the errors

List 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 format

Retrieve 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 format

HTTP 404 Success - A message describing the error

Update 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 format

HTTP 404 Success - A message describing the error

Delete 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 format

HTTP 404 Success - A message describing the error

Webhook 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 webhook signing_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.