Introduction

Welcome to the CycleSoftware API documentation

Documentation overview

API endpoints

Use the API endpoint hosts according to the country of your account;

Country code	API endpoint host
`NL`	`api.cyclesoftware.nl`
`BE`	`api.cyclesoftware.be`
`FR`	`api.cyclesoftware.fr`
`other`	`api.cyclesoftware.nl`

Requirements

To use the APIs you'll need API credentials. The API credentials are provided by CS or available in your account.

You should access the API over HTTPS
Where possible use Accept-encoding: gzip. For data api's this might be required.

Request/Response Format

The APIs consist of SOAP/WSDL webservices and JSON endpoints.

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code	Error Type
`400 Bad Request`	Invalid request, e.g. using an unsupported HTTP method, or GET variable
`401 Unauthorized`	Authentication or permission error, e.g. incorrect credentials
`403 Forbidden`	Authentication or permission error
`404 Not Found`	Requests to resources that don't exist or are missing
`429 Too Many Requests`	API limit reached, see api limiting
`500 Internal Server Error`	Server error

JSON error response

{
  "error": true,
  "error_message": "Unauthorized"
}

XML error response

<?xml version="1.0"?>
<result>
  <error>1</error>
  <error_message>Unauthorized</error_message>
</result>

SOAP error response

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>400</faultcode>
      <faultstring>The problem description</faultstring>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Errors return both an appropriate HTTP status code and response object which contains a error, and error_message

API Parameters

Almost all endpoints accept optional parameters which can be passed as an HTTP query string parameter, e.g. GET /v1/endpoint?status=completed. All parameters are documented along each endpoint.

API Pagination

For certain endpoints pagination is implemented. The mechanism differs per endpoint. But the default pagination mechanism is as follows:

JSON response

{
  "error": false,
  "error_message": null,
  "data": [],
  "pagination": {
    "next_offset": 1000
  }
}

GET /v1/endpoint?offset=1000

In the response the next_offset is suggested. You can pass the next offset in the offset GET parameter.

API Types

Some general information about responses:

Amounts could be specified in cents (which will be clear by the fieldname) or with decimal-strings

Scope	Description	Example
`string`	An UTF-8 string of variadic length	`Hello world!`
`boolean`	Boolean `true` or `false`	`true`
`integer`	64-bit signed integer	`1212`
`decimal`	Decimal number with 2 decimals e.g. `0.22`	`0.22`
`float`	A floating-point number with `.` used as the separator	`123.22`
`date`	Date in `yyyy-mm-dd` format	`2023-01-23`
`datetime`	Datetime in `yyyy-mm-dd hh:mm:ss` format	`2023-01-23 12:34:33`
`timestamp`	UNIX timestamp (seconds since Unix Epoch)	`1678348370`
`uuid`	UUID string	`20c5d026-68b3-11ec-90d6-0242ac120003`
`array`	List of sub types	`[10,22]`
`object`	An object	`{"field": 1}`

API Limits

Since may 2022 api-limits are introduced. For endpoints that implement limits the following HTTP response headers are available.

If the limit is reached, the server will respond with an HTTP 429 - Too Many Requests error.

The following HTTP headers are present in an limited endpoint response

HTTP Response header	Description
`X-RateLimit-Minutely-Limit`	Contains the number of allowed requests per minute
`X-RateLimit-Minutely-Remaining`	Contains the number of remaining requests available within moving minutely interval
`X-RateLimit-Daily-Limit`	Contains the number of daily allowed requests
`X-RateLimit-Daily-Remaining`	Contains the number of daily remaining requests
`X-RateLimit-Daily-Reset`	Contains the UNIX timestamp when the daily limit is reset

API Scopes

Scope	Description
`common`	Access common data such as employees, enums, suppliers
`e-commerce`	Access e-commerce related endpoints (stock, order-creation, articledata)
`resources`	Access object resources such as `customers`, `workshop-orders`, `repair-objects` etc.
`stock-export`	Bulk export stock data
`sales-export`	Bulk export sales data
`rental`	Rental related information
`warehouse`	Warehouse related data
`platform`	Access authorized dealer-data for sales-platforms

Authentication

CycleSoftware uses different authentication mechanisms.

HTTP Basic Authentication

The credentials consist of a username, password and api-key. The username and password should be provided using the Basic HTTP authentication http header. The api-key is usage is documented per service.

SOAP/WSDL Authentication

The credentials consist of a username, password and api-key. The username and password should be provided within the Authentication element as documented per request. For dealer_id the actual store id within the account or api-key can be provided.

Inbound orders

Access inbound deliveries and inbound backlog data

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Inbound back-log

Get a list of goods to be delivered.

GET parameter	Type	Description
`supplier_id`	integer	If supplied only the data for the specified supplier is given See common api for supplier-ids
`is_assigned`	integer	if 1 only assigned items are returned
`offset`	integer	Pagination offset. optional

HTTP request examples

GET

/api/v1/warehouse/inbound/backlog.json

GET

/api/v1/warehouse/inbound/backlog.json?supplier_id=:supplier_id&is_assigned=1&offset=:offset

Properties

Property	Type	Description
`error`	`boolean`	`true` when an error occured
`error_message`	`?string`	Error message if known
`data`	`object[]`	Array of backlog items
`data[].id`	`integer`	Unique item id `412855`
`data[].supplier_id`	`integer`	Supplier ID `2403`
`data[].is_sold_to_customer`	`boolean`	Marked as sold to customer `false`
`data[].in_transit`	`boolean`	Marked as in transit `false`
`data[].article_id`	`string`	Article ID `LV106`
`data[].barcode`	`string`	Barcode of article `8719812004299`
`data[].supplier_reference`	`string`	Reference of supplier `7171999`
`data[].supplier_reference_2`	`string`	Reference of supplier 2 `7171999`
`data[].delivery_date`	`date`	Expected delivery-date `2022-12-26`
`data[].original_delivery_date`	`date`	Original expected delivery-date `2023-01-02`
`data[].external_remarks`	`string`	Remarks from supplier
`data[].internal_remarks`	`?string`	Internal remarks
`data[].created_at`	`datetime`	Date-time created
`data[].modified_at`	`datetime`	Date-time modified
`data[].assignment`	`?object`	If not null the item is assigned
`data[].assignment.assigned_to_entity_type_id`	`integer`	Entity type assignment `20` (see common api)
`data[].assignment.assigned_to_entity_id`	`integer`	Entity ID of assignment `564840`
`data[].assignment.outbound_order_id`	`integer`	Assigned outbound order id `440452`
`data[].assignment.reference`	`string`	Reference of outbound-order `fvs_138443`
`pagination.next_offset`	`?integer`	If specified use offset in GET parameter for extra data

HTTP request

GET /api/v1/warehouse/inbound/backlog.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8

HTTP Response

HTTP/1.1 200 
Content-type: application/json; charset=utf-8
Content-length: 1330

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "id": 412805,
      "supplier_id": 2403,
      "is_sold_to_customer": false,
      "in_transit": false,
      "article_id": "LV105",
      "barcode": "8719812004282",
      "supplier_reference": "7171648",
      "supplier_reference_2": "7171648",
      "delivery_date": "2022-11-07",
      "original_delivery_date": "2022-11-14",
      "external_remarks": "",
      "internal_remarks": "some text",
      "created_at": "2022-04-21 12:15:56",
      "modified_at": "2022-04-21 12:18:53",
      "assignment": null
    },
    {
      "id": 412843,
      "supplier_id": 2403,
      "is_sold_to_customer": false,
      "in_transit": false,
      "article_id": "LV106",
      "barcode": "8719812004299",
      "supplier_reference": "7171984",
      "supplier_reference_2": "7171984",
      "delivery_date": "2022-10-24",
      "original_delivery_date": "2022-10-31",
      "external_remarks": "BL-412843",
      "internal_remarks": null,
      "created_at": "2022-04-21 12:15:56",
      "modified_at": "2022-04-21 12:18:53",
      "assignment": {
        "assigned_to_entity_type_id": 20,
        "assigned_to_entity_id": 564840,
        "outbound_order_id": 440452,
        "reference": "yourref_138443"
      }
    }
  ],
  "pagination": {
    "next_offset": 2
  }
}

Inbound delivered items

Get a list of delivered inbound goods

GET parameter	Type	Description
`start_date`	date	Start date interval (yyyy-mm-dd) required
`end_date`	date	Start date interval (yyyy-mm-dd) required
`offset`	integer	Pagination offset. optional

HTTP request examples

GET

/api/v1/warehouse/inbound/delivered-items.json?start_date=:start_date&end_date=:end_date

GET

/api/v1/warehouse/inbound/delivered-items.json?start_date=:start_date&end_date=:end_date&offset=:offset

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "article_id": "ART1",
      "barcode": "1000001",
      "datetime_delivered": "2021-01-01 12:00:33",
      "inbound_delivery_id": 10000,
      "inbound_delivery_item_id": 100001,
      "packinglist_number": "PB11",
      "purchase_price_cents": 10099,
      "quantity_missing": 0,
      "quantity_packinglist": 1,
      "quantity_scanned": 0,
      "quantity_stocked": 1,
      "supplier_id": 2113
    },
    {
      "article_id": "ART2",
      "barcode": "1000002",
      "datetime_delivered": "2021-01-01 12:00:33",
      "inbound_delivery_id": 10000,
      "inbound_delivery_item_id": 100002,
      "packinglist_number": "PB11",
      "purchase_price_cents": 10099,
      "quantity_missing": 0,
      "quantity_packinglist": 1,
      "quantity_scanned": 0,
      "quantity_stocked": 0,
      "supplier_id": 2113
    }
  ],
  "pagination": {
    "next_offset": null
  }
}

Workshop

Access workshop data

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Workshop assemblies

Get a list of stock items released for shipment

GET parameter	Type	Description
`start_date`	date	Start date interval (yyyy-mm-dd) required
`end_date`	date	Start date interval (yyyy-mm-dd) required
`offset`	integer	Pagination offset. optional

Properties

Property	Type	Description
`error`	`boolean`	e.g. `false`
`error_message`	`?string`	The error message if an error occurred
`data[].stock_item_id`	`integer`	Stock item ID e.g. `20000`
`data[].is_assembled`	`boolean`	`true` if object is assembled
`data[].released_by`	`string`	The user who released/assembled the item e.g. `Name 12`
`data[].scheduled_for_release_at`	`date`	Scheduled date for release/assembly e.g. `2021-10-10`
`data[].released_for_shipment_at`	`date`	Date of release/assembly e.g. `2021-10-11`
`data[].claimed_by_dealer_id`	`integer`	Dealer-id who claimed the stock item `5393`
`data[].outbound_order_id`	`integer`	The Outbound Order ID e.g. `20001`
`data[].outbound_order_item_id`	`integer`	The Outbound Order Item ID e.g. `20002`
`data[].outbound_shipment_id`	`integer`	The Outbound Shipment ID e.g. `20003`
`data[].outbound_shipment_item_id`	`integer`	The Outbound Shipment Item ID e.g. `20004`
`data[].is_sold_to_customer`	`boolean`	Boolean whether the item is sold
`pagination.next_offset`	`?integer`	If not null use in next paginated request in `offset` GET parameter

HTTP request examples

GET

/api/v1/warehouse/workshop/assemblies.json?start_date=:start_date&end_date=:end_date

GET

/api/v1/warehouse/workshop/assemblies.json?start_date=:start_date&end_date=:end_date&offset=:offset

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "stock_item_id": 10000,
      "is_assembled": true,
      "released_by": "Name 11",
      "scheduled_for_release_at": "2021-10-10",
      "released_for_shipment_at": "2021-10-11",
      "claimed_by_dealer_id": 5393,
      "outbound_order_id": 10001,
      "outbound_order_item_id": 10002,
      "outbound_shipment_id": 10003,
      "outbound_shipment_item_id": 10004,
      "is_sold_to_customer": true
    },
    {
      "stock_item_id": 20000,
      "is_assembled": false,
      "released_by": "Name 12",
      "scheduled_for_release_at": "2021-10-10",
      "released_for_shipment_at": "2021-10-11",
      "claimed_by_dealer_id": 5393,
      "outbound_order_id": 20001,
      "outbound_order_item_id": 20002,
      "outbound_shipment_id": 20003,
      "outbound_shipment_item_id": 20004,
      "is_sold_to_customer": false
    }
  ],
  "pagination": {
    "next_offset": null
  }
}

Stock

Access stock info for warehouse

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Stock-info

Get a list of stock items released for shipment

GET parameter	Type	Description
`stock_items`	`integer`	if set to 1 details about the stock items is provided optional
`no_remote_supplier_check`	`integer`	if set to 1 no remote supplier checks are included optional
`only_supplier_stock`	`integer`	if set to 1 only remote supplier stock is checked, store and warehouse stock is ignored optional
`only_supplier_id`	`integer`	if a supplier_id is given only this supplier will be included for supplier stock checks optional
`remote_supplier_check_if_not_in_warehouse`	`integer`	if set to 1 supplier check will always be checked there is no stock in warehouse optional
`always_remote_supplier_check`	`integer`	if set to 1 supplier check will always be checked optional

POST parameter	Type	Description
`barcodes`	`string[]`	array of barcodes

Properties

Property	Type	Description
`error`	`boolean`	true if errors occurred
`error_message`	`?string`	Error message if occurred
`data.status`	`boolean`	true if no errors occurred
`data.result_items`	`object[]`	Result per requested barcode
`data.result_items[].barcode`	`string`	Article barcode
`data.result_items[].stock_available`	`boolean`	Overall status whether stock is available
`data.result_items[].delivery_date`	`?date`	expected delivery date from supplier
`data.result_items[].delivery_date_supplier`	`?date`	expected delivery date from supplier
`data.result_items[].delivery_date_backlog`	`?date`	expected delivery date from registered backlog orders supplier
`data.result_items[].stock_supplier`	`?boolean`	true if stock available at supplier, null if not checked
`data.result_items[].stock_quantity`	`integer`	available quantity within stores+warehouse (new+demo+used+rental)
`data.result_items[].stock_quantity_stores`	`integer`	available quantity within stores
`data.result_items[].stock_quantity_warehouse`	`integer`	available quantity within warehouse
`data.result_items[].stock_stores`	`object[]`	array with stock info per store
`data.result_items[].stock_stores[].dealer_id`	`integer`	dealer-id of store
`data.result_items[].stock_stores[].store_name`	`string`	name of store
`data.result_items[].stock_stores[].store_phone`	`string`	phone number of store
`data.result_items[].stock_stores[].quantity`	`integer`	quantity including demo, used, rental models available
`data.result_items[].stock_stores[].quantity_demo`	`integer`	quantity of demo models available
`data.result_items[].stock_stores[].quantity_used`	`integer`	quantity of used models available
`data.result_items[].stock_stores[].quantity_rental`	`integer`	quantity of rental models available
`data.result_items[].supplier_id`	`?string`	used supplier_id in request
`data.result_items[].article_id`	`string`	used "barcode" in request e.g. `8719461035781`

HTTP request examples

GET

/app/api/whm/stockinfo/:barcode1/:barcode2/../../

GET

/app/api/whm/stockinfo/:barcode1/:barcode2/../../?stock_items={0,1}

GET

/app/api/whm/stockinfo/:barcode1/:barcode2/../../?no_remote_supplier_check={0,1}

GET

/app/api/whm/stockinfo/:barcode1/:barcode2/../../?only_supplier_stock={0,1}

GET

/app/api/whm/stockinfo/:barcode1/:barcode2/../../?only_supplier_id=:supplier_id

POST

/app/api/whm/stockinfo/

Response

{
  "error": false,
  "error_message": "",
  "data": {
    "status": true,
    "result_items": [
      {
        "barcode": "8719461035781",
        "stock_available": true,
        "delivery_date": null,
        "delivery_date_supplier": null,
        "delivery_date_backlog": null,
        "stock_supplier": null,
        "stock_quantity": 1,
        "stock_quantity_stores": 1,
        "stock_quantity_warehouse": 0,
        "stock_stores": [
          {
            "dealer_id": 791825,
            "store_name": "Ridderkerk",
            "store_phone": "010-1234567",
            "quantity": 1,
            "quantity_demo": 1,
            "quantity_used": 0,
            "quantity_rental": 0
          },
          {
            "dealer_id": 857361,
            "store_name": "Breda",
            "store_phone": "010-1234567",
            "quantity": 1,
            "quantity_demo": 1,
            "quantity_used": 0,
            "quantity_rental": 0
          }
        ],
        "supplier_id": null,
        "article_id": "8719461035781"
      },
      {
        "barcode": "8719461035782",
        "stock_available": false,
        "delivery_date": "01-01-2022",
        "delivery_date_supplier": "01-05-2022",
        "delivery_date_backlog": "01-01-2022",
        "stock_supplier": false,
        "stock_quantity": 0,
        "stock_quantity_stores": 0,
        "stock_quantity_warehouse": 0,
        "stock_stores": [],
        "supplier_id": null,
        "article_id": "8719461035782"
      }
    ]
  }
}

Stock list Warehouse

Get a list of objects in warehouse

Properties

Property	Type	Description
`error`	`boolean`	`true` if error occurred
`error_message`	`?string`	Error if occurred
`data`	`object[]`	array of objects
`data[].stock_item_id`	`integer`	Object ID within warehouse `325817`
`data[].outbound_order_id`	`integer`	Outbound order ID
`data[].supplier`	`string`	Supplier name
`data[].article_id`	`string`	Article number `735-18460`
`data[].barcode`	`string`	Barcode `4063518126705`
`data[].description`	`string`	Description of article `Ravenna E8F Herenfiets 28" grey 60 cm diamant`
`data[].frame_id`	`string`	Framenumber `AA01148291`
`data[].purchase_price_cents`	`integer`	Purchase price in cents
`data[].purchase_price_cents_packinglist`	`integer`	Purchase price in cents from last packinglist
`data[].dealer_rrp_cents`	`integer`	RRP in cents
`data[].claimed_for_account_id`	`?integer`	If claimed the account_id
`data[].claimed_for_store_id`	`?integer`	If claimed the store_id
`data[].is_blocked_for_claiming`	`boolean`	`true` if blocked for claiming
`data[].is_claimed_for_obo`	`boolean`	`true` if claimed for outbound order
`data[].is_sold_to_customer`	`boolean`	`true` if sold to a customer
`data[].is_shipped`	`boolean`	`true` if shipped
`data[].is_deleted`	`boolean`	`true` if item was deleted
`data[].stocked_at`	`datetime`	Datetime stocked `2021-10-22 11:33:03`
`data[].shipped_at`	`?datetime`	Datetime shipped
`data[].custom_variable_1`	`string`	Custom variable from article
`data[].custom_variable_2`	`string`	Custom variable from article
`data[].custom_variable_3`	`string`	Custom variable from article
`data[].custom_variable_4`	`string`	Custom variable from article
`data[].custom_variable_5`	`string`	Custom variable from article
`data[].warehouse_group_name`	`?string`	Warehouse group name if set e.g. `Hall`
`data[].warehouse_location`	`?string`	Warehouse location if not shipped `B-1-1`
`pagination.next_url`	`?string`	`null` if all data processed. Contains URL to next result set if more data is available

HTTP request examples

GET

/api/v2/warehouse/stock/items.json

GET

/api/v2/warehouse/stock/items.json?offset=:offset

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "stock_item_id": 109993,
      "outbound_order_id": 315254,
      "supplier": "Leopard",
      "article_id": "593005",
      "barcode": "8717931438117",
      "description": "Leopard Tess 24 inch 2019 M24-39 Zwart Mat",
      "frame_id": "17017456",
      "purchase_price_cents": 40900,
      "purchase_price_cents_packinglist": 40900,
      "dealer_rrp_cents": 41900,
      "claimed_for_account_id": 1000,
      "claimed_for_store_id": 13,
      "is_blocked_for_claiming": false,
      "is_claimed_for_obo": true,
      "is_sold_to_customer": true,
      "is_shipped": false,
      "is_deleted": false,
      "stocked_at": "2018-04-24 08:53:20",
      "shipped_at": "2021-04-13 07:59:29",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "warehouse_group_name": "Hall",
      "warehouse_location": "A-1-1"
    },
    {
      "stock_item_id": 203013,
      "outbound_order_id": 376797,
      "supplier": "Gazelle",
      "article_id": "G1539",
      "barcode": "8717231346426",
      "description": "Orange C8 HMB H8",
      "frame_id": "61380279",
      "purchase_price_cents": 279900,
      "purchase_price_cents_packinglist": 279900,
      "dealer_rrp_cents": 289900,
      "claimed_for_account_id": 1000,
      "claimed_for_store_id": 23,
      "is_blocked_for_claiming": false,
      "is_claimed_for_obo": true,
      "is_sold_to_customer": false,
      "is_shipped": true,
      "is_deleted": true,
      "stocked_at": "2020-06-11 10:59:05",
      "shipped_at": "2021-10-15 10:03:09",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "warehouse_group_name": null,
      "warehouse_location": null
    }
  ],
  "pagination": {
    "next_url": null
  }
}

Stock list POS

Get a list of stocked objects in POS

Properties

Property	Type	Description
`error`	`boolean`	`true` if error occurred e.g. `false`
`error_message`	`?string`	Error message or null
`data[].account_id`	`integer`	Account ID of store `5393`
`data[].store_id`	`integer`	ID of the POS store `2`
`data[].object_id`	`integer`	POS Object ID `20648`
`data[].warehouse_stock_item_id`	`?integer`	Item ID in warehouse e.g `2220648` (only for WHM dealers), registered since march 2024
`data[].sales_order_id`	`integer`	POS order id `1000`
`data[].supplier`	`string`	Supplier name `Gazelle`
`data[].article_id`	`string`	Article number `A1935`
`data[].barcode`	`string`	Barcode `8717231254776`
`data[].description`	`string`	Description `Gazelle Eclipse C8 LTD`
`data[].frame_id`	`string`	Framenumber `60516151`
`data[].purchase_price_cents`	`integer`	Purchase price in cents `50980`
`data[].purchase_price_cents_packinglist`	`integer`	Purchase price in cents from last packinglist `50980`
`data[].dealer_rrp_cents`	`integer`	RRP in cents `94900`
`data[].is_sold_to_customer`	`boolean`	`true` if sold to customer
`data[].is_demo`	`boolean`	`true` if marked as demo
`data[].has_invoice`	`boolean`	`true` if invoiced
`data[].stocked_at`	`date`	Custom variable from article
`data[].custom_variable_1`	`string`	Custom variable from article
`data[].custom_variable_2`	`string`	Custom variable from article
`data[].custom_variable_3`	`string`	Custom variable from article
`data[].custom_variable_4`	`string`	Custom variable from article
`data[].custom_variable_5`	`string`	Custom variable from article
`data[].is_deleted`	`boolean`	Item is deleted
`data[].is_rental`	`boolean`	If rental object `true`
`data[].is_used`	`boolean`	`true` if not a new object
`pagination.next_url`	`?string`	`null` if all data processed. Contains URL to next result set if more data is availabile

HTTP request examples

GET

/api/v2/warehouse/stock/pos-items.json

GET

/api/v2/warehouse/stock/pos-items.json?token=:token

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "account_id": 1000,
      "store_id": 6,
      "object_id": 1076,
      "warehouse_stock_item_id": null,
      "sales_order_id": 0,
      "supplier": "Batavus",
      "article_id": "BE100086",
      "barcode": "8713568256155",
      "description": "Batavus STREAM",
      "frame_id": "BA5169351",
      "purchase_price_cents": 219900,
      "purchase_price_cents_packinglist": 219900,
      "dealer_rrp_cents": 259900,
      "is_sold_to_customer": false,
      "is_demo": true,
      "has_invoice": false,
      "stocked_at": "2015-12-08",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "is_deleted": false,
      "is_used": false,
      "is_rental": false
    },
    {
      "account_id": 1000,
      "store_id": 2,
      "object_id": 4673,
      "warehouse_stock_item_id": null,
      "sales_order_id": 0,
      "supplier": "Gazelle",
      "article_id": "A0828",
      "barcode": "8717231240205",
      "description": "Gazelle Orange C8 Hm",
      "frame_id": "60467933",
      "purchase_price_cents": 190000,
      "purchase_price_cents_packinglist": 190000,
      "dealer_rrp_cents": 210000,
      "is_sold_to_customer": false,
      "is_demo": true,
      "has_invoice": false,
      "stocked_at": "2016-02-03",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "is_deleted": false,
      "is_used": true,
      "is_rental": true
    }
  ],
  "pagination": {
    "next_url": "https://api.cyclesoftware.nl/api/v2/warehouse/stock/pos-items.json?token=1243"
  }
}

Outbound orders

Outbound orders related APIs

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Open order items

Get a list of open outbound order items: quantity shipped < quantity

GET parameter	Type	Description
`:page`	`integer`	Pagination page

HTTP request examples

GET

/api/v1/warehouse/outbound/order/open-orders.json?page=:page

Property	Type	Description
`error`	`boolean`	`false` if no error occured
`error_message`	`?string`	Error message if present
`data`	`object[]`	Array of OBO items
`data[].dealer_id`	`integer`	The dealer ID e.g. `99`
`data[].outbound_order_id`	`integer`	Outbound order ID e.g. `204915`
`data[].outbound_order_item_id`	`integer`	Outbound order item ID e.g. `307229`
`data[].created_at`	`datetime`	Date time created `2019-08-15 12:48:10`
`data[].ecommerce_reference_id`	`string`	Reference ID
`data[].ecommerce_reference_text`	`string`	Reference Text
`data[].barcode`	`string`	Barcode e.g. `8717231260616`
`data[].description`	`string`	Description e.g. `Esprit C3 H 59 T3`
`data[].quantity`	`integer`	Quantity of item e.g. `1`
`data[].quantity_claimed`	`integer`	Quantity claimed e.g. `0`
`data[].quantity_shipped`	`integer`	Quantity shipped e.g. `0`
`data[].reference`	`string`	Reference to POS order
`data[].is_sold_to_customer`	`boolean`	`true` if sold to customer
`data[].is_blocked_for_claiming`	`boolean`	`true` if item is blocked for claiming
`data[].is_pooled_within_stores`	`boolean`	`true` if item is sourced within stores
`pagination.page`	`integer`	Pagination page `1`
`pagination.count`	`integer`	Count result items `262`
`pagination.has_next_page`	`boolean`	If `true` call endpoint again with `page=page+1`

HTTP Request

GET /api/v1/warehouse/outbound/order/open-orders.json?page=1 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8

HTTP Response

HTTP/1.1 200 
Content-type: application/json; charset=utf-8
Content-length: 1441
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000

{
    "error": false,
    "error_message": null,
    "data": [
        {
            "dealer_id": 4807,
            "outbound_order_id": 225,
            "outbound_order_item_id": 277,
            "created_at": "2014-01-03 15:05:16",
            "ecommerce_reference_id": "FV_121212",
            "ecommerce_reference_text": "FV_121212",
            "barcode": "8717231228326",
            "description": "Gazelle MS GRACE Dames Black 2014 49",
            "quantity": 1,
            "quantity_claimed": 0,
            "quantity_shipped": 0,
            "reference": "POS12121076",
            "is_sold_to_customer": true,
            "is_blocked_for_claiming": false,
            "is_pooled_within_stores": false
        },
        {
            "dealer_id": 4807,
            "outbound_order_id": 231,
            "outbound_order_item_id": 283,
            "created_at": "2014-01-07 15:49:15",
            "ecommerce_reference_id": "",
            "ecommerce_reference_text": "",
            "barcode": "8713568224574",
            "description": "Batavus",
            "quantity": 1,
            "quantity_claimed": 0,
            "quantity_shipped": 0,
            "reference": "F.1080",
            "is_sold_to_customer": true,
            "is_blocked_for_claiming": false,
            "is_pooled_within_stores": false
        },
    ],
    "pagination": {
        "page": 1,
        "count": 2,
        "has_next_page": false
    }
}

Convert pool to regular

Convert a POOL order to a regular order.

URL parameter	Type	Description
`:outbound_order_id`	`integer`	Outbound order id required

HTTP request examples

POST

/api/v1/warehouse/outbound/order/:outbound_order_id/pool-to-regular.json

HTTP Request

POST /api/v1/warehouse/outbound/order/1013123/pool-to-regular.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8

HTTP Response

HTTP/1.1 200 
Content-type: application/json; charset=utf-8
Content-length: 722
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000

{
  "error": false,
  "error_message": null
}

Cancel order

Cancels an outbound order and will attempt to cancel the related supplier order in POS.

URL parameter	Type	Description
`:outbound_order_id`	`integer`	Outbound order id required

HTTP request examples

POST

/api/v1/warehouse/outbound/order/:outbound_order_id/cancel.json

HTTP Request

POST /api/v1/warehouse/outbound/order/1013123/cancel.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8

HTTP Response

HTTP/1.1 200 
Content-type: application/json; charset=utf-8
Content-length: 265
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000

{
    "error": false,
    "error_message": null,
    "result": [
        {
            "outbound_order_item_id": 111,
            "unclaimed_stock": 2
        },
        {
            "outbound_order_item_id": 333,
            "unclaimed_stock": 3
        }
    ]
}

Shipments

Access outbound shipment data

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Delivery status for object item id

Mark the shipment for a stock item as delivered or not-delivered. not-delivered should be used if the package could not be delivered at the destination.

URL parameter	Type	Description
`:stock_item_id`	`integer`	Stock item ID in warehouse required

HTTP request examples

POST

/api/v1/warehouse/outbound/item/:stock_item_id/delivered.json

POST

/api/v1/warehouse/outbound/item/:stock_item_id/not-delivered.json

Response

{
  "error": false,
  "error_message": null
}

Warehouse

Access warehouse data

Authentication mechanism

Basic HTTP Authentication
Scope(s): warehouse

Available locations

Get an overview of capacity and available stock locations

Properties

Property	Type	Description
`error`	`boolean`	`true` if error occurred
`error_message`	`null`	Error message if present
`data.availability`	`object[]`	Overal availability
`data.availability[].code`	`string`	Location type code e.g. `elo`
`data.availability[].description`	`string`	Location type description e.g. `Elektrische fietsen`
`data.availability[].available_locations`	`integer`	Available locations `830`
`data.availability_per_warehouse_group`	`object[]`	Availability per warehouse group
`data.availability_per_warehouse_group[].warehouse_group_name`	`string`	e.g. `Groep 1`
`data.availability_per_warehouse_group[].availability`	`object[]`	Availability within group
`data.availability_per_warehouse_group[].availability[].code`	`string`	Location type code e.g. `elo`
`data.availability_per_warehouse_group[].availability[].description`	`string`	Location type description `Elektrische fietsen`
`data.availability_per_warehouse_group[].availability[].available_locations`	`integer`	Available locations e.g. `0`

HTTP request examples

GET

/api/v1/warehouse/availability.json

Response

{
  "error": false,
  "error_message": null,
  "data": {
    "availability": [
      {
        "code": "elo",
        "description": "Elektrische fietsen",
        "available_locations": 830
      },
      {
        "code": "elo_city",
        "description": "Elektrische fietsen & Stadsfietsen",
        "available_locations": 118
      },
      {
        "code": "cargo",
        "description": "Bakfietsen",
        "available_locations": 0
      },
      {
        "code": "city",
        "description": "Stadsfietsen",
        "available_locations": 4158
      },
      {
        "code": "child_to_20",
        "description": "Kinderfietsen t/m 20inch",
        "available_locations": 161
      },
      {
        "code": "child_above_20",
        "description": "Kinderfietsen vanaf 20inch",
        "available_locations": 0
      }
    ],
    "availability_per_warehouse_group": [
      {
        "warehouse_group_name": "Groep 1",
        "availability": [
          {
            "code": "elo",
            "description": "Elektrische fietsen",
            "available_locations": 0
          },
          {
            "code": "elo_city",
            "description": "Elektrische fietsen & Stadsfietsen",
            "available_locations": 0
          },
          {
            "code": "cargo",
            "description": "Bakfietsen",
            "available_locations": 0
          },
          {
            "code": "city",
            "description": "Stadsfietsen",
            "available_locations": 0
          },
          {
            "code": "child_to_20",
            "description": "Kinderfietsen t/m 20inch",
            "available_locations": 0
          },
          {
            "code": "child_above_20",
            "description": "Kinderfietsen vanaf 20inch",
            "available_locations": 0
          }
        ]
      },
      {
        "warehouse_group_name": "Groep 2",
        "availability": [
          {
            "code": "elo",
            "description": "Elektrische fietsen",
            "available_locations": 720
          },
          {
            "code": "elo_city",
            "description": "Elektrische fietsen & Stadsfietsen",
            "available_locations": 0
          },
          {
            "code": "cargo",
            "description": "Bakfietsen",
            "available_locations": 0
          },
          {
            "code": "city",
            "description": "Stadsfietsen",
            "available_locations": 3951
          },
          {
            "code": "child_to_20",
            "description": "Kinderfietsen t/m 20inch",
            "available_locations": 161
          },
          {
            "code": "child_above_20",
            "description": "Kinderfietsen vanaf 20inch",
            "available_locations": 0
          }
        ]
      }
    ]
  }
}

Webhooks

Receive updates from CycleSoftware for specific entities.

Webhook request

The payload is a raw POST of a JSON string to your server. Several headers are included:

Header	Description
`X-CycleSoftware-Delivery`	Unique UUID of the webhook message. Same value JSON id property
`X-CycleSoftware-Event`	Event name. Same value as JSON event_name property
`X-CycleSoftware-Signature`	HMAC of the payload using your hash secret

Payload structure

Every JSON payload has the same structure. The payload object is different per event.

Property	Type	Description
`id`	`uuid`	Unique webhook UUID `20c5d026-68b3-11ec-90d6-0242ac120003`
`account_id`	`integer`	Account ID CycleSoftware `1`
`event_name`	`string`	The event-name e.g. `sales_order.created`
`event_timestamp`	`float`	Timestamp when the message was created. `1640787926.323`
`payload`	`object`	The actual payload of the event

Payload structure

{
  "id": "20c5d026-68b3-11ec-90d6-0242ac120003",
  "account_id": 1,
  "event_name": "event.sub_name",
  "event_timestamp": 1640787926.323,
  "payload": {}
}

Outbound orders

Event name	Description
`warehouse_outbound_order.created_or_updated`	Fired when the outbound order is created or updated

Properties

Property	Type	Description
`payload.outbound_order_id`	`integer`	Outbound order ID e.g. `463681`
`payload.outbound_order_type_id`	`integer`	Type of order e.g. `1`
`payload.outbound_order_status_id`	`integer`	Status of order e.g. `1`
`payload.dealer_id`	`integer`	ID of dealer e.g. `4807`
`payload.account_id`	`integer`	ID of account of the order e.g. `4807`
`payload.store_id`	`integer`	ID of store of the order e.g. `1`
`payload.created_at`	`datetime`	Created datetime e.g. `2022-07-05 11:07:48`
`payload.datetime_preferred_delivery`	`?datetime`	e.g. `2022-07-05 11:07:48` or `null`
`payload.sales_order_id`	`?integer`	Sales order ID in POS
`payload.order_reference_text`	`string`	String with e-commerce reference from POS
`payload.order_items`	`object[]`	Array of order items
`payload.order_items[].outbound_order_item_id`	`integer`	ID of the item e.g. `605491`
`payload.order_items[].item_type_id`	`integer`	Item type id, see common api e.g. `2`
`payload.order_items[].is_active`	`boolean`	if `false` the item is marked deleted
`payload.order_items[].barcode`	`string`	Barcode of item e.g. `8713568215084`
`payload.order_items[].quantity`	`integer`	Quantity ordered `1`
`payload.order_items[].quantity_claimed`	`integer`	Quantity claimed stock e.g. `0`
`payload.order_items[].quantity_shipped`	`integer`	Quantity shipped e.g. `0`
`payload.order_items[].is_blocked_for_claiming`	`boolean`	`true` if blocked for claiming
`payload.order_items[].description`	`string`	Description of item
`payload.order_items[].remark`	`string`	Remark of order item
`payload.order_items[].reference`	`string`	Reference of order item
`payload.order_items[].is_sold_to_customer`	`boolean`	`true` if sold to customer
`payload.order_items[].is_attached_to_outbound_item_id`	`?integer`	If not null the outbound_order_item_id of which the item is attached to
`payload.order_items[].is_pooled_within_stores`	`boolean`	`true` if pool order

Payload structure

{
  "id": "180c1fd6-04ab-4215-b55a-0d8710961c95",
  "account_id": 4743,
  "event_name": "warehouse_outbound_order.created_or_updated",
  "event_timestamp": 1657012068.444,
  "payload": {
    "outbound_order_id": 463681,
    "outbound_order_type_id": 1,
    "outbound_order_status_id": 1,
    "dealer_id": 4807,
    "account_id": 4807,
    "store_id": 1,
    "created_at": "2022-07-05 11:07:48",
    "datetime_preferred_delivery": null,
    "sales_order_id": null,
    "order_reference_text": "",
    "order_items": [
      {
        "outbound_order_item_id": 605491,
        "item_type_id": 2,
        "is_active": true,
        "barcode": "8713568215084",
        "quantity": 1,
        "quantity_claimed": 0,
        "quantity_shipped": 0,
        "is_blocked_for_claiming": false,
        "description": "",
        "remark": "",
        "reference": "",
        "is_sold_to_customer": false,
        "is_attached_to_outbound_item_id": null,
        "is_pooled_within_stores": false
      }
    ]
  }
}

Warehouse stock item

Event name	Description
`warehouse_stock_item.updated`	Fired when the stock item is updated
`warehouse_stock_item.released_for_shipment`	Fired when stock item is released for shipment

Properties

Property	Type	Description
`warehouse_stock_item_id`	`integer`	Warehouse stock Item ID `285`
`warehouse_outbound_order_id`	`integer`	Outbound order ID `121212` (`0` if not associated to an order)
`warehouse_outbound_order_item_id`	`integer`	Outbound order Item ID `333233` (`0` if not associated to an order)
`warehouse_outbound_shipment_id`	`integer`	Shipment ID `0` if not shipped
`warehouse_outbound_shipment_item_id`	`integer`	Shipment Item ID `0` if not shipped
`warehouse_location.location`	`string`	Location in warehouse e.g. `R-1-2`
`warehouse_location.rack_name`	`string`	Rack name in warehouse `R`
`supplier_id`	`integer`	Supplier ID of object e.g. `2113` (see common API suppliers)
`article_id`	`string`	Article number of stock item e.g. `4961`
`barcode`	`string`	Barcode of stock item e.g. `2000100281620`
`battery_id`	`string`	Battery ID e.g. `BAT22222`
`customer_id`	`integer`	Customer ID in POS e.g. `1006`
`customer_order_id`	`integer`	Sales order ID in POS e.g. `333`
`employee_first_name`	`string`	Employee name e.g. `First`
`employee_last_name`	`string`	Employee last name e.g. `Last`
`frame_id`	`string`	Frame ID e.g. `3232`
`is_assembled`	`boolean`	`true` if item is assembled
`is_shipped`	`boolean`	`true` if item is shipped
`is_delivered`	`boolean`	`true` if item is delivered
`key_id`	`string`	Key ID of object e.g. `2323`
`lock_id`	`string`	Lock ID of object e.g. `2323`
`license_plate_number`	`string`	License plate of object e.g. `xx-yy-zz`
`order_reference_id`	`string`	POS/OBO order reference ID `fvs12222`
`order_reference_text`	`string`	POS/OBO order reference text e.g. `REF`
`labels`	`string[]`	Labels associated with object e.g. `Label 1`
`sub_order_items`	`object[]`	Arrey of sub order items associated to item
`sub_order_items[].article_id`	`string`	Article ID e.g. `a3223`
`sub_order_items[].barcode`	`string`	Article barcode e.g. `883273232332`
`sub_order_items[].is_active`	`boolean`	`true` if order item is active
`sub_order_items[].is_included`	`boolean`	`true` if item is included with item
`sub_order_items[].quantity`	`integer`	Quantity of sub item e.g. `3`
`sub_order_items[].quantity_claimed`	`integer`	Quantity stock claimed e.g. `3`
`sub_order_items[].reference`	`string`	Reference of item `ref-1`
`sub_order_items[].remark`	`string`	Remark of item `remark-1`

Payload structure

{
  "id": "180c1fd6-04ab-4215-b55a-0d8710961c95",
  "account_id": 4743,
  "event_name": "warehouse_outbound_order.created_or_updated",
  "event_timestamp": 1657012068.444,
  "payload": {
    "warehouse_stock_item_id": 285,
    "warehouse_outbound_order_id": 121212,
    "warehouse_outbound_order_item_id": 333233,
    "warehouse_outbound_shipment_id": 0,
    "warehouse_outbound_shipment_item_id": 0,
    "article_id": "4961",
    "barcode": "2000100281620",
    "battery_id": "BAT22222",
    "customer_id": 1006,
    "customer_order_id": 333,
    "employee_first_name": "First",
    "employee_last_name": "Last",
    "frame_id": "3232",
    "is_assembled": true,
    "is_shipped": false,
    "is_delivered": false,
    "key_id": "2323",
    "lock_id": "2323",
    "license_plate_number": "xx-yy-zz",
    "order_reference_id": "fvs12222",
    "order_reference_text": "REF",
    "sub_order_items": [
      {
        "article_id": "a3223",
        "barcode": "883273232332",
        "is_active": true,
        "is_included": true,
        "quantity": 2,
        "quantity_claimed": 2,
        "reference": "ref-1",
        "remark": "remark-1"
      },
      {
        "article_id": "a3223",
        "barcode": "883273232332",
        "is_active": true,
        "is_included": true,
        "quantity": 3,
        "quantity_claimed": 3,
        "reference": "ref-1",
        "remark": "remark-1"
      }
    ],
    "supplier_id": 2113,
    "warehouse_location": {
      "location": "R-1-2",
      "rack_name": "R"
    },
    "labels": [
      "Label 1"
    ]
  }
}