> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fulfill Order

> Create a fulfillment for an order

# Fulfill Order

Creates a fulfillment record for an order, marking items as shipped. You can fulfill all items at once or create partial fulfillments.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.launchmystore.io/api/v1/orders/ord_abc123/fulfillments.json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "tracking_number": "1Z999AA10123456784",
      "tracking_company": "UPS",
      "tracking_url": "https://ups.com/track?num=1Z999AA10123456784",
      "notify_customer": true,
      "line_items": [
        {
          "id": "li_xyz789",
          "quantity": 2
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.launchmystore.io/api/v1/orders/ord_abc123/fulfillments.json', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tracking_number: '1Z999AA10123456784',
      tracking_company: 'UPS',
      tracking_url: 'https://ups.com/track?num=1Z999AA10123456784',
      notify_customer: true,
      line_items: [
        {
          id: 'li_xyz789',
          quantity: 2
        }
      ]
    })
  });
  ```
</CodeGroup>

## Path Parameters

<ParamField path="orderId" type="string" required>
  The unique order ID
</ParamField>

## Body Parameters

<ParamField body="tracking_number" type="string">
  Tracking number for the shipment
</ParamField>

<ParamField body="tracking_company" type="string">
  Shipping carrier name (e.g., "UPS", "FedEx", "USPS", "DHL")
</ParamField>

<ParamField body="tracking_url" type="string">
  Full tracking URL
</ParamField>

<ParamField body="status" type="string" default="pending">
  Initial fulfillment status. One of `pending`, `open`, `success`,
  `cancelled`, `error`, `failure`. A shipped state (`success`) advances the
  order to `shipped` / `partial` based on the line items covered.
</ParamField>

<ParamField body="service_id" type="string">
  Fulfillment service ID associated with this fulfillment.
</ParamField>

<ParamField body="notify_customer" type="boolean" default="true">
  Whether to send a shipping notification email to the customer. Only sent
  when the fulfillment moves the order into a `shipped`/`partial` state.
</ParamField>

<ParamField body="line_items" type="array">
  Specific line items to fulfill. If not provided (empty), the fulfillment
  is treated as covering the whole order.

  <Expandable title="Line Item Object">
    <ParamField body="id" type="string" required>
      Line item ID
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity to fulfill (minimum `1`)
    </ParamField>
  </Expandable>
</ParamField>

## Response

On success (`201 Created`) the created fulfillment is returned under
`data.fulfillment`.

<ResponseField name="status" type="integer">
  HTTP status (`201` on success).
</ResponseField>

<ResponseField name="state" type="string">
  `success` or `error`.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message, or `null` on success.
</ResponseField>

<ResponseField name="data.fulfillment" type="object">
  The created fulfillment object.

  <Expandable title="Fulfillment Object">
    <ResponseField name="fulfillmentId" type="string">
      Unique fulfillment ID
    </ResponseField>

    <ResponseField name="orderId" type="string">
      Associated order ID
    </ResponseField>

    <ResponseField name="status" type="string">
      Fulfillment status: `pending`, `open`, `success`, `cancelled`, `error`, `failure`
    </ResponseField>

    <ResponseField name="serviceId" type="string">
      Fulfillment service ID, or `null`
    </ResponseField>

    <ResponseField name="trackingNumber" type="string">
      Tracking number
    </ResponseField>

    <ResponseField name="trackingCompany" type="string">
      Shipping carrier
    </ResponseField>

    <ResponseField name="trackingUrl" type="string">
      Tracking URL
    </ResponseField>

    <ResponseField name="lineItems" type="array">
      The line items submitted for this fulfillment (`[]` when fulfilling the whole order)
    </ResponseField>

    <ResponseField name="notifyCustomer" type="boolean">
      Whether the customer was notified
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Creation timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last update timestamp (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "status": 201,
  "state": "success",
  "message": null,
  "data": {
    "fulfillment": {
      "fulfillmentId": "9f1c2e4a-...",
      "orderId": "ord_abc123",
      "status": "success",
      "serviceId": null,
      "trackingNumber": "1Z999AA10123456784",
      "trackingCompany": "UPS",
      "trackingUrl": "https://ups.com/track?num=1Z999AA10123456784",
      "lineItems": [
        {
          "id": "li_xyz789",
          "quantity": 2
        }
      ],
      "notifyCustomer": true,
      "createdAt": "2024-01-25T10:00:00Z",
      "updatedAt": "2024-01-25T10:00:00Z"
    }
  },
  "count": null,
  "pagination": null
}
```

## Tracking Company

`tracking_company` is stored verbatim as the carrier label — there is no
fixed list of accepted values and no carrier normalization. Send the
carrier name you want shown (e.g. `"UPS"`, `"FedEx"`) and, where useful,
the full `tracking_url`.

## Error Codes

| Status | Description                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body (e.g. a line item missing `id`/`quantity`, or a malformed `tracking_url`) |
| `401`  | Invalid or missing access token                                                                |
| `403`  | App doesn't have the `write_orders` scope                                                      |
| `404`  | Order with the specified ID does not exist                                                     |
| `500`  | Unexpected server error while creating the fulfillment                                         |