NAV Navbar
shell
  • Introduction
  • Authentication
  • Account Info
  • General
  • Inbound Orders
  • Outbound Orders
  • Consignments
  • Products
  • Standard Elements
  • Responses
  • Introduction

    This is the official CartonCloud API version 1 documentation.

    For general application documentation please refer to our Knowledge Base.

    Accept-Version: 1

    Last Updated: 2019-10-30 00:18

    Authentication

    CartonCloud authentication follows the OAuth2 specifications.

    Tenants and customers integrating with the API are required to use the client credentials grant type to obtain an Access Token.

    Client Credentials

    An access token can be obtained using the client credentials

    HTTP Request

    Example Request

    curl -u {clientId}:{clientSecret} \ 
       "https://api.cartoncloud.com/uaa/oauth/token" \
       -X POST \
       -H "Accept-Version: 1" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d grant_type="client_credentials"
    

    POST https://api.cartoncloud.com/uaa/oauth/token

    Authentication

    The following client credentials can be obtained from a user with administrator access. The clientId and clientSecret should be set in the HTTP Basic Auth Header

    Credential Description
    clientId The username for requests to the token end point
    clientSecret The password for requests to the token end point

    Request Parameters

    Parameter Description
    grant_type Must be client_credentials

    Response Properties

    Example Response JSON

    {
      "access_token": "{accessToken}",
      "token_type": "bearer",
      "expires_in": 3600
    }
    
    Property Description
    access_token Access token to be used to authenticate subsequent API requests
    token_type Will always be bearer
    expires_in The number of seconds after which the access token will expiry and will no longer be valid

    Access Token

    Example Request

    # Send the access token with every request
    curl "https://api_endpoint" \
      -H "Accept-Version: 1" \
      -H "Authorization: Bearer {accessToken}"
    

    With every API request a valid access token must be supplied in the request header as a Bearer Tokens

    Authorization: Bearer {accessToken}

    Software Vendors

    Software vendors interested in providing out of the box integration into CartonCloud are required to use OAuth2 authorization code flow to connect.

    Account Info

    User

    Returns information about the currently authenticated user.

    Request

    Example Request

    curl "https://api.cartoncloud.com/uaa/userinfo" \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}"
    

    GET https://api.cartoncloud.com/uaa/userinfo

    Response

    Example Response JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b1234",
      "name": "John Smith",
      "email": "john.smith@cartoncloud.com",
      "tenants": [
        {
          "id": "318782ea-75b1-11e8-adc0-fa7ae01babab",
          "name": "Demo Tenant"
        }
      ]
    }
    

    On success will return status code 200 OK with the user info in the response body.

    JSON Property Description
    id
    name
    email
    tenants id
    tenants name

    General

    General features and requirements for API end points

    Version

    All API end points will require an Accept-Version in the request header. Failure to provide the header will return a status code of 400, however, an invalid version can return a 404 or 400.

    Accept-Version: 1

    In general all changes to this API will be made in a non-breaking manner (fields added, but not removed). However, if breaking changes are required the version number will be incremented. The old version will be maintained for up to 12 months before being removed, or if no use is detected over 30 continuous days.

    Tenant

    All API end points, except for authentication, will be within the context of a tenant identified by a unique identifier (UUID)

    Request

    GET https://api.cartoncloud.com/tenants/{tenantId}/api_endpoint

    URL Parameter Description
    tenantId The UUID for the tenant to be accessed

    Pagination

    For search requests and other end points which return multiple elements, data will be paged and the headers below returned.

    Request

    GET https://api.cartoncloud.com/tenants/{tenantId}/api_endpoint?pageNumber=5&pageSize=20

    Query Parameter Description Default
    pageNumber The page number to return results for 1
    pageSize The number of elements per page varies with end point

    Response

    Header Description
    Total-Pages Total number of pages of data that is available for the request
    Page-Size The number of elements per page
    Page-Number The page number for the returned results
    Total-Elements The total number of elements that is available for the request
    Link Links to other pages as Web Links

    Inbound Orders

    Create Inbound Order

    Create a new inbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders" \
       -X POST \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    Example Request JSON

    {
      "type": "INBOUND",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {
        "urgent": true,
        "instructions": "",
        "arrivalDate": "2018-01-31"
      },
      "properties": {
        "myCustomField": "info"
      },
      "items": [
        {
          "properties": {
            "expiryDate": "2018-10-25",
            "batch": "AAAA"
          },
          "details": {
            "product": {...},
            "unitOfMeasure": {
              "type": "UNITS"
            }
          },
          "measures": {
            "quantity": 25
          }
        },
        {
          "properties": {
            "expiryDate": "2018-10-22",
            "batch": "BBBB"
          },
          "details": {
            "product": {...},
            "unitOfMeasure": {
              "type": "CASES"
            }
          },
          "measures": {
            "quantity": 2
          }
        }
      ]
    }
    

    POST https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders

    URL Property Description
    tenantId UUID for the tenant
    JSON Property Type Required Description
    type String - The type of the order. This defaults to INBOUND when making a request to this endpoint
    status Status - Status for the order. Set to DRAFT to make it a draft order, otherwise will be assigned the initial status based on workflow.
    references References Yes Secondary references for the order
    customer Customer Yes Customer for which the order is for
    warehouse Warehouse - Warehouse for which the order is for. If not provided will be assigned to the default warehouse
    details urgent Boolean - true for urgent orders
    instructions String - Special instructions related to the order
    arrivalDate String - The arrival date for the order
    properties {custom} * - Custom fields relating to the order
    items properties {custom} * - Custom fields relating to the item (eg. batch, expiry, etc.)
    details product Product Yes The product for the item
    unitOfMeasure UnitOfMeasure - The unit of measure the product will be created with. If not provided the default for the product will be used.
    measures quantity Decimal Yes The quantity of the given product for the item

    Response

    Example Response JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b9ebc",
      "type": "INBOUND",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "properties": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 201 Created with the created order in the response body. The data structure will be the same as in the above request, with the following additional properties.

    JSON Property Description
    id UUID for the order
    version Version number for the entity

    Get Inbound Order

    Retrieves a previously created inbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders/{id}" \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders/{id}

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the order

    Response

    Example Response JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b9ebc",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 200 OK with the order in the response body. For details on the response data refer to create end point

    Update Inbound Order

    Updates a previously created inbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders/{id}" \
       -X PUT \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "If-Match: {version}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/inbound-orders/{id}

    For details on the request data refer to response for create

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the order
    Header Description
    If-Match Version number for the current entity

    Response

    Example Response JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b9ebc",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 2
    }
    

    On success will return status code 200 OK with the updated order in the response body. For details on the response data refer to response for create

    Inbound Order Status Change Notification

    When an inbound order changes status to a specified status a webhook can be called

    Webhook Request

    Example Request

    POST https://api.client.com/customisable

    The HTTP headers included in the request can be customised also to include authentication details. OAuth and other expiring authentication tokens are not supported for webhooks.

    Request

    Example Request JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b9ebc",
      "status": "RECEIVED",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    The full inbound order is included in the request body. For details on the data refer to create end point

    Outbound Orders

    Create Outbound Order

    Create a new outbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders" \
       -X POST \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    Example Request JSON

    {
      "type": "OUTBOUND",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {
        "urgent": true,
        "instructions": "",
        "collect": {
          "requiredDate": "2018-06-21"
        },
        "deliver": {
          "address": {...},
          "instructions": "Leave by front door",
          "requiredDate": "2018-06-22",
          "cashPaymentAmount": {...}
        },
        "invoiceValue": {...}
      },
      "properties": {
        "myCustomField": "info"
      },
      "items": [
        {
          "properties": {
            "expiryDate": "2018-10-25",
            "batch": "AAAA"
          },
          "details": {
            "product": {...},
            "unitOfMeasure": {
              "type": "UNITS"
            }
          },
          "measures": {
            "quantity": 25
          }
        },
        {
          "properties": {
            "expiryDate": "2018-10-22",
            "batch": "BBBB"
          },
          "details": {
            "product": {...},
            "unitOfMeasure": {
              "type": "CASES"
            }
          },
          "measures": {
            "quantity": 2
          }
        }
      ]
    }
    

    POST https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders

    URL Property Description
    tenantId UUID for the tenant
    JSON Property Type Required Description
    type String - The type of the order. This defaults to OUTBOUND when making a request to this endpoint
    references References Yes Secondary references for the order
    customer Customer Yes Customer for which the order is for
    warehouse Warehouse - Warehouse for which the order is for. If not provided will be assigned to the default warehouse
    details urgent Boolean - true for urgent orders
    instructions String - Special instructions related to the order
    collect requiredDate Date - Date the order should be shipped or collected from warehouse
    deliver address Address Yes Address to deliver order to
    instructions String - Special delivery instructions
    requiredDate Date - Date the order should be delivered
    cashPaymentAmount Money - Cash on delivery amount to be paid
    invoiceValue Money - Total invoice value for the order
    properties {custom} * - Custom fields relating to the order
    items properties {custom} * - Custom fields relating to the item (eg. batch, expiry, etc.)
    details product Product Yes Product for the item
    unitOfMeasure UnitOfMeasure - The unit of measure the product will be created with. If not provided the default for the product will be used.
    measures quantity Decimal Yes The quantity of the given product for the item

    Response

    Example Response JSON

    {
      "id": "fb5b56f6-a68e-11e8-98d0-529269fb1459",
      "type": "OUTBOUND",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "properties": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 201 Created with the created order in the response body. A 228 Created with issues status code will be returned for outbound orders created in a rejected status typically due to stock issues. The data structure will be the same as in the above request, with the following additional properties.

    JSON Property Description
    id UUID for the order
    version Version number for the entity

    Get Outbound Order

    Retrieves a previously created outbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders/{id}" \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders/{id}

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the order

    Response

    Example Response JSON

    {
      "id": "fb5b56f6-a68e-11e8-98d0-529269fb1459",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 200 OK with the order in the response body. For details on the response data refer to response for create

    Update Outbound Order

    Updates a previously created outbound order

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders/{orderId}" \
       -X PUT \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "If-Match: {version}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/outbound-orders/{id}

    For details on the request data refer to response for create

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the order
    Header Description
    If-Match Version number for the current entity

    Response

    Example Response JSON

    {
      "id": "fb5b56f6-a68e-11e8-98d0-529269fb1459",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 2
    }
    

    On success will return status code 200 OK with the updated order in the response body. For details on the response data refer to create end point

    Outbound Order Status Change Notification

    When an outbound order changes status to a specified status a webhook can be called

    Webhook Request

    Example Request

    POST https://api.client.com/customisable

    The HTTP headers included in the request can be customised also to include authentication details. OAuth and other expiring authentication tokens are not supported for webhooks.

    Request

    Example Request JSON

    {
      "id": "fb5b56f6-a68e-11e8-98d0-529269fb1459",
      "status": "DISPATCHED",
      "references": {...},
      "customer": {...},
      "warehouse": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    The full outbound order is included in the request body. For details on the data refer to create end point

    Consignments

    Create Consignment

    Create a new consignment

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/consignments" \
       -X POST \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    Example Request JSON

    {
      "references": {...},
      "customer": {...},
      "details": {
        "collect": {
          "address": {...},
        },
        "deliver": {
          "address": {...},
          "instructions": "Leave by front door",
          "requiredDate": "2018-06-22",
          "cashPaymentAmount": {...}
        }
        "invoiceValue": {...}
      },
      "properties": {
        "serviceType": "EXPRESS",
        "myCustomField": "info"
      },
      "items": [
        {
          "properties": {
            "description": "misc equipment"
          },
          "measures": {
            "pallets": 2,
            "weight": 120,
            "quantity": 10
          }
        },
        {
          "measures": {
            "pallets": 3,
            "weight": 160
          },
          "details": {
            "product": {
              "references": {
                "code": "DRUM"
              }
            }
          }
        }
      ]
    }
    

    POST https://api.cartoncloud.com/tenants/{tenantId}/consignments

    URL Property Description
    tenantId UUID for the tenant
    JSON Property Type Required Description
    type String - The type of the order. This defaults to CONSIGNMENT when making a request to this endpoint
    references References Yes Secondary references for the consignment
    customer Customer Yes Customer for which the consignment is for
    details collect address Address - Address to collect consignment from (defaults to depot)
    deliver address Address - Address to deliver consignment to (defaults to depot)
    requiredDate Date - Date the consignment should be delivered
    instructions String - Special delivery instructions
    cashPaymentAmount Money - Cash on delivery amount to be paid
    invoiceValue Money - Total invoice value for the consignment
    properties {custom} * - Custom fields relating to the consignment
    items properties description String - Free text description of item being transported
    {custom} * - Custom fields relating to the item
    measures pallets Integer - Total number of pallets for the item
    weight Decimal - Total weight of the item
    volume Decimal - Total volume of the item
    quantity decimal - Quantity of the product
    details product Product - Product for the item

    Response

    Example Response JSON

    {
      "id": "028ff38c-a68f-11e8-98d0-529269fb1459",
      "type": "CONSIGNMENT",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "details": {...},
      "properties": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 201 Created with the created consignment in the response body. The data structure will be the same as in the above request, with the following additional properties.

    JSON Property Description
    id UUID for the consignment
    status Status of the consignment
    version Version number for the entity

    Get Consignment

    Retrieves a previously created consignment

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/consignments/{id}" \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/consignments/{id}

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the consignment

    Response

    Example Response JSON

    {
      "id": "028ff38c-a68f-11e8-98d0-529269fb1459",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    On success will return status code 200 OK with the order in the response body. For details on the response data refer to response for create

    Update Consignment

    Updates a previously created consignment

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/consignments/{id}" \
       -X PUT \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "If-Match: {version}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    GET https://api.cartoncloud.com/tenants/{tenantId}/consignments/{id}

    For details on the request data refer to response for create

    URL Property Description
    tenantId UUID for the tenant
    id UUID for the consignment
    Header Description
    If-Match Version number for the current entity

    Response

    Example Response JSON

    {
      "id": "028ff38c-a68f-11e8-98d0-529269fb1459",
      "status": "DRAFT",
      "references": {...},
      "customer": {...},
      "details": {...},
      "items": [...],
      "version": 2
    }
    

    On success will return status code 200 OK with the updated consignment in the response body. For details on the response data refer to response for create

    Consignment Status Change Notification

    When an consignment changes status to a specified status a webhook can be called

    Webhook Request

    Example Request

    POST https://api.client.com/customisable

    The HTTP headers included in the request can be customised also to include authentication details. OAuth and other expiring authentication tokens are not supported for webhooks.

    Request

    Example Request JSON

    {
      "id": "028ff38c-a68f-11e8-98d0-529269fb1459",
      "status": "DELIVERED",
      "references": {...},
      "customer": {...},
      "details": {...},
      "items": [...],
      "version": 1
    }
    

    The full consignment is included in the request body. For details on the data refer to create end point

    Products

    Create Product

    Create a new product

    Request

    Example Request

    curl "https://api.cartoncloud.com/tenants/{tenantId}/products" \
       -X POST \
       -H "Accept-Version: 1" \
       -H "Authorization: Bearer {accessToken}" \
       -H "Content-Type: application/json" \
       -d "{JSON AS BELOW}"
    

    POST https://api.cartoncloud.com/tenants/{tenantId}/products

    Warehouse Product

    Example Warehouse Product Request JSON

    {
      "scope": "WAREHOUSE",
      "references": {...},
      "customer": {...},
      "type": "FROZEN",
      "name": "Ice Cream",
      "description": "Chocolate ice cream 4L",
      "details": {
        "uiOptions": {...},
        "variableWeight": true,
        "storage": {
          "chargeMethod": "PER_LOCATION"
        },
        "inbound": {
          "initialStatus": "QC"
        },
        "stockSelection": {
          "method": "FEFO",
          "secondaryMethod": "MINIMISE_STORAGE",
          "strict": true,
          "expiryThresholdDays": 10
        }
      },
      "itemPropertyRequirements": {
        "expiry": "REQUIRED",
        "batch": "OPTIONAL"
      },
      "defaultUnitOfMeasure": "cartons",
      "unitOfMeasures": {
        "units": {
          "qtyPerBase": 1,
          "weight": 1.2,
          "volume": 0.25
        },
        "cartons": {
          "qtyPerBase": 10
        },
        "pallets": {
          "qtyPerBase": 100
        }
      },
      "notifications": [
        {
          "type": "STOCK_EXPIRY",
          "thresholdDays": 20
        },
        {
          "type": "STOCK_LOW"
        }
      ]
    }
    
    URL Property Description
    tenantId UUID for the tenant
    JSON Property Type Required Description
    scope String Yes WAREHOUSE for warehousing product
    type String Yes Product types are defined per tenant
    references References Yes Secondary references for the product
    customer Customer Yes Customer for which the product is for
    name String Yes Short name for the product
    description String Yes Full product description
    details variableWeight Boolean - true for variable weight products
    uiOptions UiOption - UI Options for controlling how the Product is displayed in certain screens
    storage chargeMethod String - PER_LOCATION, ``
    inbound initialStatus String - Initial product status when first received
    stockSelection method String - FEFO, FIFO
    secondaryMethod String - MINIMISE_STORAGE
    strict Boolean - Strict selection method
    expiryThresholdDays Integer - Expiry threshold days
    itemPropertyRequirements {custom} String - REQUIRED, OPTIONAL
    defaultUnitOfMeasure String Yes
    unitOfMeasures {unit of measure} qtyPerBase Decimal Yes Quantity of base unit of measure per one of this unit of measure
    weight Decimal - Weight per unit of measure
    volume Decimal - Volume per unit of measure
    notifications - List of notifications applicable to this product
    type String Yes Notification type
    * * * Varies depending on notification

    Transport Product

    Example Transport Product Request JSON

    {
      "scope": "TRANSPORT",
      "references": {...},
      "customer": {...},
      "type": "FROZEN",
      "name": "Ice Cream",
      "description": "Chocolate ice cream 4L",
      "properties": {
        "length": 10
      },
      "details": {
        "uiOptions": {
          "consignmentItems": {
            "cubicCalculator": {
              "multiplierField": "QUANTITY"
            }
          }
        }
      },
      "measures": {
        "weight": 1.3
      }
    }
    
    URL Property Description
    tenantId UUID for the tenant
    JSON Property Type Required Description
    scope String Yes TRANSPORT for transport product
    type String Yes Product types are defined per tenant
    references References Yes Secondary references for the product
    customer Customer - Customer if product is for a specific customer only
    name String Yes Short name for the product
    description String Yes Full product description
    properties {custom} - Custom properties associated with an entity (length, width, height etc.)
    details uiOptions consignmentItems cubicCalculator/multiplierField - The default field for the Cubic Multiplier in the consignment items Cubic Calculator functionality
    measures {custom} - Measures associated with an entity (weight, volume etc.)

    Response

    Example Response JSON

    {
      "id": "318782ea-75b1-11e8-adc0-fa7ae01b9ebc",
      ...
      "version": 1
    }
    

    On success will return status code 201 Created with the created order in the response body. The data structure will be the same as in the above request, with the following additional properties.

    JSON Property Description
    id UUID for the product
    status Status for the product
    version Version number for the entity

    Standard Elements

    References

    {
      "customer": "REF-1234",
      "alternateReference": "ALT-REF-5678"
    }
    

    References are a set of external or alternate references for the resource. These may or may not be unique depending on the specific configuration for the tenant and customer. The primary reference or identifier for resources will always be the id which is an UUID

    Property Description
    customer Customer supplied reference
    {reference type} Other custom references maybe defined for the tenant

    Customer

    {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "name": "Customer A",
      "references": {
        "code": "C123456"
      }
    }
    

    A customer can be referenced using any one of the properties below. Where multiple properties are supplied the first property as listed below will be used.

    Property Description
    id UUID for the customer
    references code Customer code
    name Name of the customer

    Warehouse

    {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "name": "Example Warehouse"
    }
    

    A warehouse can be referenced using any one of the properties below. Where multiple properties are supplied the first property as listed below will be used.

    Property Description
    id UUID for the warehouse
    name Name of the warehouse

    Address

    {
      "companyName": "Company A",
      "contactName": "Mr Smith",
      "address1": "Unit 2, Corporate Tower",
      "address2": "1 Main Street",
      "suburb": "Springfield",
      "city": "Metropolis",
      "state": {...},
      "postcode": "4000",
      "country": {...},
      "phone": "07 5512 3456",
      "email": "info@company.com"
    }
    
    Property Type Description
    companyName String Name of the company
    contactName String Contact person's name
    address1 String First line of street address
    address2 String Second line of street address
    suburb String Suburb
    city String City
    state State State, region or prefecture information
    postcode String Post code (zip code)
    country Country Country information
    phone String Phone number
    email String Email address

    State

    {
      "code": "QLD",
      "name": "Queensland"
    }
    

    A state can be referenced using any one of the properties below. Where multiple properties are supplied the first property as listed below will be used.

    Property Description
    code The code used to denote the state
    name The name of the state

    Country

    {
      "name": "Australia",
      "iso2Code": "AU",
      "iso3Code": "AUS"
    }
    

    A country can be referenced using any one of the properties below. Where multiple properties are supplied the first property as listed below will be used.

    Property Description
    iso2Code The (ISO Alpha-2 Code) Code of the country
    iso3Code The (ISO Alpha-3 Code) Code of the country
    name The name of the country

    Product

    {
      "id": "c3706e8c-7526-11e8-adc0-fa7ae01b3ebc",
      "name": "Product Name",
      "references": {
          "code": "SKU123",
          "barcode": "00123246586"
      }
    }
    

    A product can be referenced using any one of the properties below. Where multiple properties are supplied the first property as listed below will be used.

    Property Description
    id UUID for the product
    references code Product code
    barcode Product barcode
    name Name of the Product

    UnitOfMeasure

    {
      "type": "CARTON"
    }
    

    A unit of measure can be referenced using the property below.

    Property Description
    type The code of the unit of measure being used

    Money

    {
      "amount": 1000,
      "currency": "AUD"
    }
    
    Property Type Description
    amount Decimal The amount being used for the field
    currency String The currency being used for the field

    Responses

    Success Status Codes

    The following HTTP status codes are used for successful requests.

    Status Code Description Reason
    200 Success Successfully completed request
    201 Created The entity was successfully created
    228 Created with issues The entity was created, but has issues that may need to be addressed

    Error Status Codes

    If there are any errors with the request, an error status code will be returned along with further details of the error in the response body as an array of JSON error objects.

    Status Code Description Reason
    400 Bad Request Request is invalid
    401 Unauthorized Access token or credentials are not valid
    403 Forbidden No permissions to access the resource
    404 Not Found The resource does not exist, is an invalid URL or unknown version
    405 Method Not Allowed Invalid method (GET, POST, PUT, etc.)
    409 Conflict Operation cannot be performed as the resource has been modified by another request
    422 Unprocessable Entity Structure of the request is valid, but data content is invalid or not compatible with the request
    429 Too Many Requests Rate limiting has been applied
    500 Internal Server Error An issue with our server. Try again later.
    503 Service Unavailable Temporarily offline for maintenance. Try again later.

    Error Response Data

    General

    Example Response JSON

    [
      {
        "message": "Request method 'PUT' not supported"
      }
    ]
    

    Some errors will simply return a text description of the error encountered, but will still follow the same data structure.

    Property Description
    message A description of the error

    Validation

    A request data validation error will return the error code 422 and the following response

    Example Response JSON

    [
      {
        "field": "/name",
        "message": "Name cannot be empty."
      },
      {
        "field": "/description",
        "message": "Description cannot be empty."
      }
    ]
    

    An array of validation errors with the fields for which the error applies will be returned.

    Property Description
    field The property field for which the error applies as a JSON Pointer
    message A description of the validation error