Create Fulfillment
curl --request POST \
--url https://production-api.puppetvendors.com/fulfillments \
--header 'Content-Type: application/json' \
--header 'x-access-token: <api-key>' \
--data '
{
"lineItemIds": [
"<string>"
],
"trackingNumber": "<string>",
"shippingCarrier": "<string>",
"trackingUrl": "<string>",
"notifyCustomer": true
}
'import requests
url = "https://production-api.puppetvendors.com/fulfillments"
payload = {
"lineItemIds": ["<string>"],
"trackingNumber": "<string>",
"shippingCarrier": "<string>",
"trackingUrl": "<string>",
"notifyCustomer": True
}
headers = {
"x-access-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
lineItemIds: ['<string>'],
trackingNumber: '<string>',
shippingCarrier: '<string>',
trackingUrl: '<string>',
notifyCustomer: true
})
};
fetch('https://production-api.puppetvendors.com/fulfillments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://production-api.puppetvendors.com/fulfillments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'lineItemIds' => [
'<string>'
],
'trackingNumber' => '<string>',
'shippingCarrier' => '<string>',
'trackingUrl' => '<string>',
'notifyCustomer' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-access-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/fulfillments"
payload := strings.NewReader("{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-access-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://production-api.puppetvendors.com/fulfillments")
.header("x-access-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/fulfillments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}"
response = http.request(request)
puts response.read_bodyFulfillments
Create Fulfillment
Fulfill line items with tracking information as a vendor
POST
/
fulfillments
Create Fulfillment
curl --request POST \
--url https://production-api.puppetvendors.com/fulfillments \
--header 'Content-Type: application/json' \
--header 'x-access-token: <api-key>' \
--data '
{
"lineItemIds": [
"<string>"
],
"trackingNumber": "<string>",
"shippingCarrier": "<string>",
"trackingUrl": "<string>",
"notifyCustomer": true
}
'import requests
url = "https://production-api.puppetvendors.com/fulfillments"
payload = {
"lineItemIds": ["<string>"],
"trackingNumber": "<string>",
"shippingCarrier": "<string>",
"trackingUrl": "<string>",
"notifyCustomer": True
}
headers = {
"x-access-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
lineItemIds: ['<string>'],
trackingNumber: '<string>',
shippingCarrier: '<string>',
trackingUrl: '<string>',
notifyCustomer: true
})
};
fetch('https://production-api.puppetvendors.com/fulfillments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://production-api.puppetvendors.com/fulfillments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'lineItemIds' => [
'<string>'
],
'trackingNumber' => '<string>',
'shippingCarrier' => '<string>',
'trackingUrl' => '<string>',
'notifyCustomer' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-access-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/fulfillments"
payload := strings.NewReader("{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-access-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://production-api.puppetvendors.com/fulfillments")
.header("x-access-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/fulfillments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"lineItemIds\": [\n \"<string>\"\n ],\n \"trackingNumber\": \"<string>\",\n \"shippingCarrier\": \"<string>\",\n \"trackingUrl\": \"<string>\",\n \"notifyCustomer\": true\n}"
response = http.request(request)
puts response.read_bodyV2 Alpha — This endpoint is part of the V2 API preview. Breaking changes may occur.
Overview
Create a fulfillment for one or more line items belonging to the authenticated vendor. This creates a fulfillment in Shopify and updates the line item records in PuppetVendors. Optionally sends a shipping notification to the customer.Vendor Token Required — This endpoint requires a vendor-scoped JWT token. Merchant tokens will receive a 403 error.
Use Cases
- Automate fulfillment from a vendor’s warehouse or 3PL system
- Bulk-fulfill orders by scripting API calls from a shipping platform
- Connect external fulfillment services to the vendor’s workflow
Request Body
string[]
required
Array of PuppetVendors line item IDs (
_id values) to fulfill. At least one is required. All line items must belong to the authenticated vendor.string
Shipment tracking number.
string
Shipping carrier name (e.g.
"Royal Mail", "UPS", "FedEx").string
URL for tracking the shipment. Must be a valid URL.
boolean
default:"false"
Whether to send a shipping notification email to the customer.
Response
200
{
"success": true,
"data": {
"success": true,
"fulfillments": [
{
"type": "success",
"lineItemId": "507f1f77bcf86cd799439015",
"message": "Fulfillment completed successfully."
}
]
}
}
Partial Failure
If some items fail to fulfill, each item reports individually:200
{
"success": true,
"data": {
"success": true,
"fulfillments": [
{ "type": "success", "lineItemId": "507f1f77bcf86cd799439015", "message": "Fulfillment completed successfully." },
{ "type": "error", "lineItemId": "507f1f77bcf86cd799439016", "message": "Already fulfilled" }
]
}
}
Error Responses
400
{
"success": false,
"error": {
"message": "Failed to create fulfillments",
"code": "FULFILLMENT_FAILED"
}
}
Example
curl -X POST https://production-api.puppetvendors.com/fulfillments \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_VENDOR_JWT_TOKEN" \
-d '{
"lineItemIds": ["507f1f77bcf86cd799439015", "507f1f77bcf86cd799439016"],
"trackingNumber": "RM123456789GB",
"shippingCarrier": "Royal Mail",
"trackingUrl": "https://tracking.royalmail.com/RM123456789GB",
"notifyCustomer": true
}'
More Examples
Fulfill with tracking and notify customercurl -X POST https://production-api.puppetvendors.com/fulfillments \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_VENDOR_JWT_TOKEN" \
-d '{
"lineItemIds": ["665a1b2c3d4e5f6a7b8c9d0e", "665a1b2c3d4e5f6a7b8c9d0f"],
"trackingNumber": "9400111899223100012345",
"shippingCarrier": "USPS",
"trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223100012345",
"notifyCustomer": true
}'
Was this page helpful?
⌘I