Manage order fulfillment

Order fulfillment covers the entire process from when a customer places an order to final delivery, including order processing, shipping, tracking, and post-sales services. Efficient fulfillment management helps reduce delivery time, improve customer satisfaction, optimize inventory control, and minimize operational costs.

Genstore enables developers to build fulfillment management apps that integrate directly with the platform, automating the order fulfillment process to enhance logistics efficiency and overall fulfillment experience.

The diagram below illustrates a sample lifecycle of an order fulfillment process within a fulfillment management app:

Prerequisites

Before managing order fulfillment via the API, ensure:

• Your app has read_orders and write_fulfillments permissions. Learn more about API access scopes and how to configure them.
• Your store has unfulfilled orders that require processing.
• You are familiar with the Orders API and the Fulfillment API.

API overview

API Endpoint	Description
/api/202412/orders?limit={n}&financialStatus=paid&fulfillmentStatus=unfulfilled	Retrieve orders, filterable by status (e.g., unfulfilled orders)
/api/202412/fulfillment	Create a fulfillment record for an order
/api/202412/fulfillments/{fulfillmentId}	Manage a specific fulfillment record

Use case: Get unfulfilled orders

Overview

Before fulfilling an order, the app must first get unfulfilled orders or check the fulfillment status of shipped orders.

Request:

GET /api/202412/orders?limit={n}&financialStatus=paid&fulfillmentStatus=unfulfilled

curl --request GET \
  --url 'https://{your-development-store}.genmystore.com/api/202412/orders?limit=10&financialStatus=paid&fulfillmentStatus=unfulfilled' \
  --header 'x-genstore-access-token: {access-token}' \
'

Response:

The API returns order details, including order ID, status, and shipping address.

{
    "id":"300157930096874",
    "financialStatus":"paid",
    "fulfillmentStatus":"unfulfilled",
    "shippingAddress": {
        "address1": "Street 123",
        "address2": "Building A, Floor 5",
        "city": "Metropolis",
        "country": "XX",
        "firstName": "John",
        "lastName": "Doe",
        "zip": "000000",
        "phone": "+999000111222"
    }
}

Use case: Create fulfillment record

overview

After retrieving an unfulfilled order, the app creates a fulfillment record by assigning a tracking number and calling the Create fulfillment API.

Request:

POST /api/202412/fulfillment

curl --request POST \
  --url https:///{your-development-store}.genmystore.com/api/202412/fulfillment \
  --header 'Content-Type: application/json' \
  --header 'x-genstore-access-token: {access-token}' \
  --data '{
    "fulfillment":{
        "orderId":300157930096874,
        "trackingNumber":"090909090900",
        ...
    }

}'

Use case: Update fulfillment tracking info

Overview

If tracking details change after fulfillment (e.g., a new tracking number or carrier update), the app must sync the latest tracking information using the Update fulfillment API.

Request:

PUT /api/202412/fulfillments/{fulfillmentId}

curl -X PUT \ 
"https://{your-development-store}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/update_tracking" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillment":{
		"lineItems":[
			{
				"variantTitle":"",
				"quantity":"",
				"productId":"",
				"title":"",
				"fulfillmentStatus":"",
				"requiresShipping":"",
				"price":"",
				"giftCard":"",
				"name":"",
				"id":"",
				"variantId":"",
				"grams":"",
				"sku":""
			}
		],
		"orderId":"",
		"trackingUrl":"",
		"createTime":"",
		"originAddress":[
			{
				"zip":"",
				"address2":"",
				"city":"",
				"address1":"",
				"countryCode":"",
				"provinceCode":""
			}
		],
		"trackingCompany":"",
		"trackingNumbers":"",
		"updateTime":"",
		"id":"",
		"trackingNumber":"",
		"trackingUrls":"",
		"status":""
	}
}'

Use case: Cancel fulfillment

Overview

If an order is canceled, the app must cancel the fulfillment record. This can be automated by subscribing to the Order cancellation webhook.

Request:

PUT /api/202412/fulfillments/{fulfillmentId}/cancel

curl -X PUT \ 
"https://{your-development-store}.genmystore.com/api/202412/fulfillments/{fulfillmentId}/cancel" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"fulfillmentId":"237894043"
}'

Webhook

To automate order and fulfillment processes, subscribe to the following webhooks for real-time updates on fulfillment status.

Webhook Topic	Description
orders/fulfilled	Triggered when an order is fully fulfilled
orders/partiallyFulfilled	Triggered when an order is partially fulfilled
orders/cancelled	Triggered when an order is canceled
refunds/create	Triggered when a refund is processed (includes refund statuses and transaction updates)