Job Basics

Once an agreement between a provider and a company is active, jobs will be created each time that an order is created with a delivery method covered by the agreement. Please note that fulfilment agreements tie one of your offerings with one of the company's delivery methods so agreements can be considered 'per-delivery-method' rather than per company.

The Job Lifecycle

A job is created when an order is created which uses a delivery method that matches a fulfilment agreement.
A job can be updated to dispatched, delivered or cancelled, all of which can represent the end of the lifecycle at this time (as there may be cases where recorded delivery is not in place).

Get Jobs

Request

GET REQUEST (/fulfilment/jobs?status=pending|dispatched|cancelled)

Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXX

Parameters

You can supply a query parameter to filter jobs by their state. States include pending, dispatched and cancelled.

Response

The response will return a list of jobs matching the request provided.

[
    {
        "id": 1,
        "company": {
            "id": 1,
            "name": "Example Company",
            "company_terms_url": null
        },
        "delivery_method_name": "Gift Envelope",
        "delivery_method_description": "Gift envelope (Fulfilled by Courier)",
        "option_name": "Gift Card in a Luxury Envelope",
        "option_description": "Delivered in a decorative, padded envelope",
        "order_reference": "rEJzAQ732r",
        "tracking_reference": null,
        "delivery_date": "2024-11-27 16:10:50",
        "delivery_address": {
            "first_name": "John",
            "last_name": "Smith",
            "line1": "Bank Chambers, High Street",
            "line2": "High Street",
            "city": "Newbridge",
            "county": "Newport",
            "postcode": "NP11 4EY"
        },
        "vouchers": [
            {
                "name": "Celebration Package",
                "value": "40.00",
                "code": "98198049",
                "to": "John",
                "from": "Jack",
                "message": "Happy Birthday!"
            }
        ],
        "tickets": []
    }
]

Update Job

Request

PUT REQUEST (/fulfilment/jobs/{jobId})

Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXX

Request Body

In the body, you can pass a status and a tracking_reference. The status must be one of dispatched, delivered or cancelled. The tracking_reference is a string that may not exceed 255 characters, this may be for a postage service or your own internal reference, it may also be omitted if you do not wish to use it.

{
    "status": "dispatched",
    "tracking_reference": "TRACKREF#1"
}

Response

The response will return the updated job object.

{
    "id": 1,
    "company": {
        "id": 1,
        "name": "Example Company",
        "company_terms_url": null
    },
    "delivery_method_name": "Gift Envelope",
    "delivery_method_description": "Gift envelope (Fulfilled by Courier)",
    "option_name": "Gift Card in a Luxury Envelope",
    "option_description": "Delivered in a decorative, padded envelope",
    "order_reference": "rEJzAQ732r",
    "tracking_reference": "TRACKREF#1",
    "delivery_date": "2024-11-27 16:10:50",
    "delivery_address": {
        "first_name": "John",
        "last_name": "Smith",
        "line1": "Bank Chambers, High Street",
        "line2": "High Street",
        "city": "Newbridge",
        "county": "Newport",
        "postcode": "NP11 4EY"
    },
    "vouchers": [
        {
            "name": "Celebration Package",
            "value": "40.00",
            "code": "98198049",
            "to": "John",
            "from": "Jack",
            "message": "Happy Birthday!"
        }
    ],
    "tickets": [],
    "received_at": "2024-11-27 16:18:40",
    "dispatched_at": "2024-11-27 16:27:37"
}

Error Responses

Error responses related to Fulfilment Jobs are typically a result of an invalid filter value being passed in with the API request, however they may also be returned due to invalid configurations or if an unexpected error occurs. Please review Error Responses for guidance on dealing with errors.