Orderspace API

Welcome to the Orderspace API reference. This document contains everything needed to access and use the API.

Getting Started

Add an App from the Apps section of the Orderspace admin to provide access to the API.

The Orderspace API supports two types of App, Private and Public.

Private Apps

Private Apps are designed for custom integrations with a specific Orderspace site. Authentication is performed by exchanging the app's keys directly for an access token. This kind of app should be used when working directly with a trusted developer on an integration designed specifically for your site.

Public Apps

Public Apps are designed for integrations with third-party products and services where the app 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 app through the web site.

Support for public apps is still under development and will be available soon. If you are developing an app for use by multiple Orderspace sites, start off with a Private App and we can upgrade it to a Public App when this feature becomes available.

Request/Response Format

The Orderspace API is organised around REST using predicatable 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 is or_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.

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 Apps

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 Apps are authenticated using the OAuth2 Client Credentials grant flow.

To obtain an access token, post the app'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 of new, active or closed

• 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 addresses

  Child 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 addresses

  Child 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 to null if there is no minimum spend

• payment_terms_id string

  The ID of the Payment Terms assigned to this customer. Set to null if no Payment Terms are assigned

• customer_group_id string

  The ID of the Customer Group assigned to this customer. Set to null if no Customer Group is assigned

• price_list_id string

  The ID of the Price List assigned to this customer. Set to null 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 of new, active or closed

• 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",
    }
    "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 of new, invoiced, released, part_fulfilled, preorder, fulfilled, standing_order or cancelled

• 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 addresses

  Child 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

• 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 address

  Child 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 as order 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 enabled

    Child 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"
    },
    "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",
      }
      "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 of new, invoiced, released, part_fulfilled, preorder, fulfilled, standing_order or cancelled

• 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",
    }
    "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 order

  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

• 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.

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

• 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 with options 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's variant_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 rate

    Child Attributes

    • id string

      The ID of the price list

    • unit_price number

      The unit price of the product variant for this price list. Set to null 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 variant

  • backorder boolean

    Determines if the product variant can be ordered when there is no stock available. Set to false, only the stock available can be ordered

  • minimum 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 variant

  • multiple number

  • weight number

    The weight of this variant in kg. Used for shipping price calculations

  • tax_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 required

  • location 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 in

  Child 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 enabled

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

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"
    },
    {...},
    {...}
  ],
  "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 of true or false

• category_id optional

  Return products in the specified category

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

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

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

• 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 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
      }
    ],
    "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 orders

  Child 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 to true if the invoice has been paid in full

• proforma boolean

  Set to true if this is a proforma invoice

• comments string

  Comments to be shown on the invoice

• address hash

  The customer's billing address

  Child 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 as invoice 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

• 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 invoice

  Child 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