Fulfillments API

Manage the fulfillments for an order. A fulfillment records which items were
shipped together, along with carrier and tracking details. An order can have
several fulfillments, which is useful when items ship separately.

Endpoints

• List Fulfillments - GET /api/v1/orders/{id}/fulfillments/
• Create Fulfillment - POST /api/v1/orders/{id}/fulfillments/
• Get Fulfillment - GET /api/v1/orders/{id}/fulfillments/{fulfillment_id}/
• Update Fulfillment - PUT /api/v1/orders/{id}/fulfillments/{fulfillment_id}/
• Delete Fulfillment - DELETE /api/v1/orders/{id}/fulfillments/{fulfillment_id}/
• Revert Fulfillment - POST /api/v1/orders/{id}/fulfillments/{fulfillment_id}/revert/

List Fulfillments

Retrieve the fulfillments for an order. This endpoint is not paginated and does
not include line items. Fetch a single fulfillment to see its items.

Endpoint: GET /api/v1/orders/{id}/fulfillments/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "ful_d0b6fmv28q6vn14peun0",
      "number": 1,
      "status": "label_created",
      "tracking_number": "1Z999AA10123456784",
      "tracking_url": "https://example.com/track/1Z999AA10123456784",
      "carrier_id": 1,
      "items": [],
      "created_at": "2023-01-02T09:00:00Z",
      "updated_at": "2023-01-02T09:30:00Z"
    }
  ]
}

Create Fulfillment

Create a fulfillment for one or more ordered items. Supply the
order_variant_id from the order's items array (see
Orders). Quantities are applied against the
order and reduce the variant's inventory for physical products.

Endpoint: POST /api/v1/orders/{id}/fulfillments/

Permission Required: Write

Request Body

{
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "quantity": 1
    }
  ]
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "items": [
      { "order_variant_id": "orv_d0b6fmv28q6vn14peun0", "quantity": 1 }
    ]
  }'

Response

Status: 201 Created

{
  "id": "ful_d0b6fmv28q6vn14peun0"
}

Error Responses

No items supplied

Status: 400 Bad Request

{
  "error": "A fulfillment requires at least one item",
  "code": "INVALID_FIELD"
}

Negative quantity

Status: 400 Bad Request

{
  "error": "Quantity must be non-negative",
  "code": "INVALID_FIELD"
}

Order not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Get Fulfillment

Retrieve a single fulfillment, including its line items.

Endpoint: GET /api/v1/orders/{id}/fulfillments/{fulfillment_id}/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/ful_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "ful_d0b6fmv28q6vn14peun0",
  "number": 1,
  "status": "label_created",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://example.com/track/1Z999AA10123456784",
  "carrier_id": 1,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "quantity": 1,
      "price": 1999
    }
  ],
  "created_at": "2023-01-02T09:00:00Z",
  "updated_at": "2023-01-02T09:30:00Z"
}

Update Fulfillment

Update a fulfillment's carrier, tracking details, or item quantities.

Endpoint: PUT /api/v1/orders/{id}/fulfillments/{fulfillment_id}/

Permission Required: Write

Request Body

{
  "carrier_id": 1,
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://example.com/track/1Z999AA10123456784",
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "quantity": 1
    }
  ]
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/ful_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "carrier_id": 1,
    "tracking_number": "1Z999AA10123456784"
  }'

Response

Status: 204 No Content

Delete Fulfillment

Delete a fulfillment.

Endpoint: DELETE /api/v1/orders/{id}/fulfillments/{fulfillment_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/ful_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Revert Fulfillment

Revert a fulfillment, returning its items to the unfulfilled pool and restoring
inventory.

Endpoint: POST /api/v1/orders/{id}/fulfillments/{fulfillment_id}/revert/

Permission Required: Write

Request

curl -X POST "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/fulfillments/ful_d0b6fmv28q6vn14peun0/revert/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-24680"

Response

Status: 204 No Content

Fulfillment Object

Fields

Fulfillment Item Object

Fields

Fulfillment Status Values

• unfulfilled
• prelabel
• on_hold
• label_created
• in_transit
• out_for_delivery
• failed_attempt
• delivered
• available_for_pickup
• exception