Item Fulfillment POST API Documentation

Purpose

This API is used to create a new item fulfillment record associated with a specific invoice. It records the shipment or delivery details of items included in the invoice, such as fulfillment status, fulfillment date, tracking information, and quantities fulfilled. The API also allows the system to auto-generate fulfillment IDs and tracking numbers if they are not provided in the request.

Use Case

When an order is processed and items are ready for delivery or shipment, this endpoint helps logistics or fulfillment teams to record item-level fulfillment data against the corresponding invoice. It is typically used after invoice creation to track which items have been shipped, packed, or remain pending. The fulfillment data integrates seamlessly with order and inventory management modules to ensure accurate record-keeping and real-time tracking of shipped goods.

Path Parameters

Parameter	Type	Description
invoice_id	String	Unique identifier of the invoice for which the item fulfillment is being created.

Query Parameters

This API does not support query parameters.

Request Body

                JSON
              

                      {
    "item_fulfillments": {
        "status": "{{fulfillment_status}}",
        "date": "{{fulfillment_date}}",
        "id": "{{custom_fulfillment_id}}",
        "tracking_number": "{{tracking_number}}",
        "note": "{{fulfillment_note}}",
        "fulfillments": [
            {
                "item_uuid": "{{item_uuid}}",
                "fulfillment_quantity": "{{quantity_fulfilled}}",
                "uuid": "{{fulfillment_uuid}}"
            }
        ]
    }
}

                    

Attribute	Type	Description
item_fulfillments	Object	Root object containing fulfillment details for the invoice.
item_fulfillments.status	String	Current fulfillment status (example: PENDING, SHIPPED, DELIVERED).
item_fulfillments.date	String	Date of fulfillment in YYYY-MM-DD format.
item_fulfillments.id	String	Custom fulfillment ID. If not provided, the system generates one automatically.
item_fulfillments.tracking_number	String	Tracking number associated with the shipment. If not provided, the system generates one automatically.
item_fulfillments.note	String	Optional note or description related to the fulfillment (example: packaging details).
item_fulfillments.fulfillments	Array	List of individual item fulfillment entries.
item_fulfillments.fulfillments.item_uuid	String	Unique identifier of the item being fulfilled.
item_fulfillments.fulfillments.fulfillment_quantity	String	Quantity of the item being fulfilled.
item_fulfillments.fulfillments.uuid	String	Unique identifier for the specific fulfillment line item.

Response

Upon successful creation, the API returns the complete fulfillment record associated with the specified invoice. This includes details such as fulfillment status, order linkage, fulfillment and tracking identifiers, fulfillment quantities, and audit information (created by, timestamps, version). The response confirms that fulfillment data has been recorded and linked to the corresponding order and invoice for downstream tracking and reporting.

Response Body

                JSON
              

                      {
    "invoice": {
        "item_fulfillment": {
            "status": "{{fulfillment_status}}",
            "date": "{{fulfillment_date_time}}",
            "id": "{{fulfillment_id}}",
            "order_id": "{{order_id}}",
            "invoice_id": "{{invoice_id}}",
            "tracking_number": "{{tracking_number}}",
            "note": "{{fulfillment_note}}",
            "fulfillments": [
                {
                    "item_uuid": "{{item_uuid}}",
                    "item_id": "{{item_id}}",
                    "uom": "{{unit_of_measure}}",
                    "warehouse": "{{warehouse_name}}",
                    "fulfillment_quantity": "{{quantity_fulfilled}}",
                    "fulfillment_left": "{{remaining_quantity}}",
                    "uuid": "{{fulfillment_uuid}}"
                }
            ],
            "created_by": "{{created_by_user}}",
            "created_on": "{{creation_timestamp}}",
            "last_updated_by": "{{last_updated_by_user}}",
            "last_updated_on": "{{last_update_timestamp}}",
            "uuid": "{{fulfillment_record_uuid}}",
            "version": "{{version_number}}"
        }
    }
}

                    

Attribute	Type	Description
invoice	Object	Root object containing the updated invoice information.
invoice.item_fulfillment	Object	Object containing details of the item fulfillment record.
invoice.item_fulfillment.status	String	Current fulfillment status (example: SHIPPED, PENDING, DELIVERED).
invoice.item_fulfillment.date	String	Fulfillment date and time in ISO 8601 format.
invoice.item_fulfillment.id	String	Fulfillment identifier, either user-defined or system-generated.
invoice.item_fulfillment.order_id	String	Identifier of the order linked to this fulfillment.
invoice.item_fulfillment.invoice_id	String	Identifier of the invoice for which fulfillment is created.
invoice.item_fulfillment.tracking_number	String	Tracking number for the shipment.
invoice.item_fulfillment.note	String	Note or description associated with the fulfillment.
invoice.item_fulfillment.fulfillments	Array	List of fulfilled items within this fulfillment record.
invoice.item_fulfillment.fulfillments.item_uuid	String	Unique identifier of the fulfilled item.
invoice.item_fulfillment.fulfillments.item_id	String	Internal item identifier linked to the fulfillment.
invoice.item_fulfillment.fulfillments.uom	String	Unit of measure used for fulfillment (if applicable).
invoice.item_fulfillment.fulfillments.warehouse	String	Warehouse or location from where the item was fulfilled.
invoice.item_fulfillment.fulfillments.fulfillment_quantity	String	Quantity fulfilled in this record.
invoice.item_fulfillment.fulfillments.fulfillment_left	String	Quantity remaining to be fulfilled for this item.
invoice.item_fulfillment.fulfillments.uuid	String	Unique identifier for the specific fulfillment line.
invoice.item_fulfillment.created_by	String	Username or identifier of the user who created the fulfillment.
invoice.item_fulfillment.created_on	String	Timestamp when the fulfillment record was created.
invoice.item_fulfillment.last_updated_by	String	Username or identifier of the user who last updated the fulfillment record.
invoice.item_fulfillment.last_updated_on	String	Timestamp of the last update made to the fulfillment record.
invoice.item_fulfillment.uuid	String	System-generated unique identifier for the fulfillment record.
invoice.item_fulfillment.version	String	Version number of the fulfillment record.