Depot Endpoints

Depot management and listing

Availability

This endpoint is available to both administrators and manufacturers.

Data Structures

Depot Record

{
    "id": 1234,
    "external_id": "DEPOT123",
    "manufacturer_id": 7891,
    "depot_name": "Boggy Creek Factory",
    "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
    "contact_person": "Harry Henderson",
    "contact_email": "harry@example.com",
    "contact_phone": "0412123123",
    "freight_pickup_option": 3,
    "depot_default_delivery_charge": 12,
    "depot_pickup_fee": 50,
    "is_default": false
}

Field	Type	Description
`id`	ID	Unique identifier
`external_id`	ID	Unique identifier of depot from external source
`manufacturer_id`	ID	Identifier of the manufacturer the customer belongs to
`depot_name`	string	Name of the depot as shown to users
`depot_address`	string	Physical address of the depot
`contact_person`	string	Name of the customer contact at the depot
`contact_email`	email	String containing the customer contact email address
`contact_phone`	phone number	Customer contact phone number
`freight_pickup_option`	bit field	Available pickup / freight options: 0x1 = Pickup; 0x2 = Delivery; 0x3 = Both
`depot_pickup_fee`	money	Amount customers are charged to pick up at this depot
`depot_default_delivery_charge`	money	Default delivery charge. Set this to `-1` to use the customer's default delivery amount instead
`is_default`	boolean	Whether this depot is the default option for customers

Creation

Depots are created by sending a POST request to /api/depot/add.

Request

The request consists of a single Depot record only.

Note:

The id key will be silently ignored
The manufacturer_id key will be silently ignored if the API key used belongs to a manufacturer. In this case, the manufacturer_id will be set to the ID of the manufacturer the API key belongs to.

Response

If the depot is successfully updated, this will return a 200 status code and a response containing a single depot record. Note that the success response is identical to the response returned when listing or updating a depot.

If the depot cannot be created, this will return an appropriate status code and an error response explaining how the depot creation failed. Note that the list of error messages returned is not exhaustive and multiple attempts may be required to resolve all issues preventing the depot from being created.

Example Error Response

POST /api/depot/add

{
    "depot_name": "Boggy Creek Factory",
    "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
    "contact_person": "Harry Henderson",
    "contact_email": "harry@example.com",
    "contact_phone": "0412123123",
    "freight_pickup_option": 3,
    "depot_default_delivery_charge": 12,
    "depot_pickup_fee": 50,
    "is_default": false
}

{
    "success": 0,
    "error": "Invalid freight pickup option specified"
}

Example Success Response

POST /api/depot/add

{
    "depot_name": "Boggy Creek Factory",
    "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
    "contact_person": "Harry Henderson",
    "contact_email": "harry@example.com",
    "contact_phone": "0412123123",
    "freight_pickup_option": 3,
    "depot_default_delivery_charge": 12,
    "depot_pickup_fee": 50,
    "is_default": false
}

{
    "success": 1,
    "depot": {
        "id": 1234,
        "external_id": null,
        "manufacturer_id": 7891,
        "depot_name": "Boggy Creek Factory",
        "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
        "contact_person": "Harry Henderson",
        "contact_email": "harry@example.com",
        "contact_phone": "0412123123",
        "freight_pickup_option": 3,
        "depot_default_delivery_charge": 12,
        "depot_pickup_fee": 50,
        "is_default": false
    }
}

Listing

A list of depots is returned from GET requests to /api/depots.

This endpoint supports search criteria.

Response

This returns a response containing a list of Depot records and other depot related metadata.

Example

GET /api/depots

{
    "success": 1,
    "data": [
        "depots": [
            "id": 1234,
            "external_id": null,
            "manufacturer_id": 7891,
            "depot_name": "Boggy Creek Factory",
            "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
            "contact_person": "Harry Henderson",
            "contact_email": "harry@example.com",
            "contact_phone": "0412123123",
            "freight_pickup_option": 3,
            "depot_default_delivery_charge": -1,
            "depot_pickup_fee": 0,
            "is_default": true
        ], [
            "id": 2345,
            "external_id": null,
            "manufacturer_id": 7891,
            "depot_name": "Warnambool Warehouse",
            "depot_address": "535 Whites Rd, Warnambool, Victoria, 3280 Australia",
            "contact_person": "Harry Henderson",
            "contact_email": "harry@example.com",
            "contact_phone": "0412123123",
            "freight_pickup_option": 1,
            "depot_default_delivery_charge": 0,
            "depot_pickup_fee": 50,
            "is_default": false
        ],
        "setting": [
            "manufacturer_id": 7891,
            "identification": "Pickup location",
            "selectable_by_customer": true,
            "enable_multiple_depot": true,
            "is_depot_functionality_enabled": true
        ]
    ]
}

Updating

Updating depot records is performed by sending a POST request to /api/depot/edit/<ID>.

Request

The request consists of a single Depot record only.

Note:

The id key in the data sent as part of the request will be silently ignored and the ID in the URL used instead.
The manufacturer_id key will be silently ignored.

Response

If the depot cannot be updated, this will return an appropriate status code and an error response explaining how the depot updating failed. Note that the list of error messages returned is not exhaustive and multiple attempts may be required to resolve all issues preventing the depot from being updated.

Example Error Response

POST /api/depot/edit/1234

{
    "depot_name": "Boggy Creek Factory",
    "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
    "contact_person": "Harry Henderson",
    "contact_email": "harry@example.com",
    "contact_phone": "0412123123",
    "freight_pickup_option": 3,
    "depot_default_delivery_charge": 12,
    "depot_pickup_fee": 50,
    "is_default": false
}

{
    "success": 0,
    "error": "Invalid freight pickup option specified"
}

Example Success Response

POST /api/depot/edit/1234

{
    "depot_name": "Boggy Creek Factory",
    "external_id": "DEPOT1234",
    "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
    "contact_person": "Harry Henderson",
    "contact_email": "harry@example.com",
    "contact_phone": "0412123123",
    "freight_pickup_option": 3,
    "depot_default_delivery_charge": 12,
    "depot_pickup_fee": 50,
    "is_default": false
}

{
    "success": 1,
    "depot": {
        "id": 1234,
        "external_id": "DEPOT1234",
        "manufacturer_id": 7891,
        "depot_name": "Boggy Creek Factory",
        "depot_address": "123 Summer St, Boggy Creet, Victoria, 3268 Australia",
        "contact_person": "Harry Henderson",
        "contact_email": "harry@example.com",
        "contact_phone": "0412123123",
        "freight_pickup_option": 3,
        "depot_default_delivery_charge": 12,
        "depot_pickup_fee": 50,
        "is_default": false
    }
}

Deleting

Depots can be deleted by sending a DELETE request to /api/depot/delete/<ID>.

Response

If the depot is successfully deleted, this will return a 200 status code with an empty JSON response. If you require a copy of the deleted depot record, you are expected to retrieve this via other means before issuing the delete request. Once the DELETE request has been processed, the depot and all associated data will not be available.

If the depot cannot be deleted, this will return an appropriate status code and an error response explaining how the depot deletion failed. Note that the list of error messages returned is not exhaustive and multiple attempts might be required to resolve all issues preventing the depot from being deleted.

Example Error Response

DELETE /api/depot/delete/1234

{
    "success": 0,
    "error": "Depot in use"
}

Example Success Response

DELETE /api/depot/delete/1234

{
    "success": 1
}