Developer Docs

Fulfillments

Read fulfillment state, create fulfillments, and attach tracking updates.

GET

/api/integrations/v1/fulfillments

List fulfillments

Returns merchant fulfillments with tracking and line-level fulfillment items.

POST

/api/integrations/v1/fulfillments

Create fulfillment

Creates a merchant-native fulfillment against an existing merchant order.

POST

/api/integrations/v1/fulfillments/:fulfillmentId/tracking

Attach tracking

Adds or updates tracking information for an existing merchant fulfillment.

GET

/api/integrations/v1/fulfillments

Read fulfillments

List fulfillments

Use this endpoint to sync the current fulfillment state for merchant orders.

Query Parameters

Supported inputs for this operation.

status

stringOptional

Filter by fulfillment status.

Example: pending

updated_after

ISO-8601 timestampOptional

Return fulfillments updated after this timestamp.

Example: 2026-03-12T18:15:00.000Z

limit

integerOptional

Maximum number of rows returned per page.

Default: 50

cursor

stringOptional

Opaque cursor from a previous response page.

Name	Type	Required	Description
status	string	No	Filter by fulfillment status. Example: pending
updated_after	ISO-8601 timestamp	No	Return fulfillments updated after this timestamp. Example: 2026-03-12T18:15:00.000Z
limit	integer	No	Maximum number of rows returned per page. Default: 50
cursor	string	No	Opaque cursor from a previous response page.

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/fulfillments" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

/api/integrations/v1/fulfillments

Write fulfillments

Create fulfillment

Use the merchant order id and the merchant order item ids returned from the orders API. Idempotency keys are recommended for retry safety.

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Idempotency-Key

stringOptional

Recommended for write safety.

Example: fulfillment-create-001

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.
Idempotency-Key	string	No	Recommended for write safety. Example: fulfillment-create-001

Request Body

JSON payload fields accepted by this endpoint.

merchant_order_id

uuidRequired

Merchant order id to fulfill.

items

arrayRequired

Line items to fulfill.

items[].merchant_order_item_id

uuidRequired

Merchant order item id from the order payload.

items[].quantity

integerRequired

Quantity to fulfill for the line item.

carrier_name

stringOptional

Carrier name associated with the fulfillment.

service_level

stringOptional

Shipping service level label.

Field	Type	Required	Description
merchant_order_id	uuid	Yes	Merchant order id to fulfill.
items	array	Yes	Line items to fulfill.
items[].merchant_order_item_id	uuid	Yes	Merchant order item id from the order payload.
items[].quantity	integer	Yes	Quantity to fulfill for the line item.
carrier_name	string	No	Carrier name associated with the fulfillment.
service_level	string	No	Shipping service level label.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X POST "https://merchants.rarely.co/api/integrations/v1/fulfillments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant_order_id": "9b9a41bc-2a15-46b9-b25b-79bb4d1a2221",
  "items": [
    {
      "merchant_order_item_id": "9f3384a7-19b7-4c04-99fe-2db52a7d9b00",
      "quantity": 1
    }
  ],
  "carrier_name": "UPS",
  "service_level": "Ground"
}'

POST

/api/integrations/v1/fulfillments/:fulfillmentId/tracking

Write fulfillments

Attach tracking

Tracking numbers are required. Idempotency keys are recommended for retry safety.

Path Parameters

Supported inputs for this operation.

fulfillmentId

uuidRequired

Merchant fulfillment id returned by the fulfillments API.

Example: 5637785e-8596-4ae0-bcfc-4db8c1a729f8

Name	Type	Required	Description
fulfillmentId	uuid	Yes	Merchant fulfillment id returned by the fulfillments API. Example: 5637785e-8596-4ae0-bcfc-4db8c1a729f8

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Idempotency-Key

stringOptional

Recommended for write safety.

Example: fulfillment-tracking-001

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.
Idempotency-Key	string	No	Recommended for write safety. Example: fulfillment-tracking-001

Request Body

JSON payload fields accepted by this endpoint.

tracking_number

stringRequired

Carrier tracking number.

tracking_url

stringOptional

Public tracking URL if available.

carrier_name

stringOptional

Carrier display name.

service_level

stringOptional

Shipping service level label.

Field	Type	Required	Description
tracking_number	string	Yes	Carrier tracking number.
tracking_url	string	No	Public tracking URL if available.
carrier_name	string	No	Carrier display name.
service_level	string	No	Shipping service level label.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X POST "https://merchants.rarely.co/api/integrations/v1/fulfillments/:fulfillmentId/tracking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tracking_number": "1Z9999999999999999",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z9999999999999999",
  "carrier_name": "UPS",
  "service_level": "Ground"
}'

Live PlaygroundClient memory only

Test live requests against your merchant integration API.

The docs app proxies requests server-side to the merchant API. Your API key stays in local browser memory for the current docs session and is never stored by this UI.

Operation

Auth mode

API key

Query: status

Query: updated_after

Query: limit

Query: cursor

Resolved request

https://merchants.rarely.co/api/integrations/v1/fulfillments

Live Output

Switch between the generated request and the most recent live response.

Generated cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/fulfillments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fulfillments

Search developer docs