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)
GET REQUEST (/fulfilment/jobs?after=date|datetime)

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.

You may also wish to query jobs for recent changes, you can do this by using the after query parameter, which will return all jobs that have been updated since the time provided so that you can update them in your application.

Response

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

[
    {
        "id": 1,
        "status": "pending",
        "company": {
            "id": 1,
            "name": "The Conservatory",
            "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!",
                "pdf_copy": "<pdf download endpoint>"
            }
        ],
        "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,
    "status": "dispatched",
    "company": {
        "id": 1,
        "name": "The Conservatory",
        "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!",
            "pdf_copy": "<pdf download endpoint>"
        }
    ],
    "tickets": [],
    "received_at": "2024-11-27 16:18:40",
    "dispatched_at": "2024-11-27 16:27:37"
}

Download PDF

Request

GET REQUEST (/fulfilment/assets/{jobId}/voucher-pdf/{voucherId}/{headerOption})

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

Unlike other endpoints in this API, this one requires application/pdf in the Accept header as you're retrieving the PDF content. You should also add application/json as a secondary type as an error feedback will be formatted as json in line with other error messages in the API. You do not need to generate the URL for this request in your code, if it is available then it will be included in the vouchers object of the get jobs response, just include the listed headers.

PDF Headers

When you set up your fulfilment options with us, we'll ask about your PDF requirements so that assets are generated along with each job. If you are an existing provider that requires PDFs for one of your fulfilment options, please get in touch.

Response

The response will return PDF asset if it exists or an error if it does not.

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.