Introduction
PuppetVendors API enables you to manage all your shop resources programmatically. Be it getting access to your vendors, users, shops, payouts, fulfillment, or commissions.
The PuppetVendors API follows the general patterns of REST.
What made this section unhelpful for you?
Base URL
Production:
https://api.puppetvendors.com/
What made this section unhelpful for you?
Errors
PuppetVendors API uses the following status or error codes.
The API rate limit is 100 requests per minute.
What made this section unhelpful for you?
Status Codes
200
Everything worked as expected.
400
The request was unacceptable, often due to missing a required parameter.
401
The request was unacceptable, often due to missing a required parameter.
402
The parameters were valid but the request failed.
403
The API key doesnt have permissions to perform the request.
404
The requested resource does not exist.
429
You have made too many consecutive requests. Please slow down and try again later.
500
We had a problem with our server. Try again later.
422
Incomplete data is provided to perform an action.
What made this section unhelpful for you?
Authentication
PuppetVendors uses API keys to allow access to the API. Access to the API is only available to shops on the Enterprise plan.
You must exchange your API key for a JWT token used for making direct API calls to your shop resources within PuppetVendors.
| Title | Required? | Type | Description | Min Length | Max Length |
|---|---|---|---|---|---|
| apiKey | true | string | Unique API Key | ||
| shopDomain | true | string | Unique Shopify Domain |
Both apiKey and shopDomain can be found in the API Access navigation under Settings.
PuppetVendors expects the JWT token to be included in all subsequent API requests to the server in a header.
Each JWT token is valid for 12 hours.
Header Parameters
Body Parameters
Response
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU0NTA4NDE0LCJleHAiOjE2NTQ1OTQ4MTR9.y7sXXNGgo32HphvaZnpv2u3vlm6BVzBQzFTDNKUTpAk",
"shopDomain": "lilydale-3.myshopify.com"
}Vendors
are your business partners, drop shippers, artists, and consignors you work with whom you wish to share your sales commissions with on PuppetVendors.
The Vendor resource allows you to manage their business information including but not limited to their name, commission type, commission rate, and business profile.
Users
are vendor staffs or owner who receives login credentials to the vendor portal.
Each vendor staff or owner account will only be able to view their own sale line items, orders, payouts, fulfillment, etc.
Reports
The reports API allows you to query vendor-specific order information to generate reports to your needs.
Payouts
represent the money owed to your business partners, drop shippers, artists, and consignors.
The payouts API allows you to query payouts information based on multiple parameters to meet your business requirements.
Fulfillments
indicate whether items whether physical or digital have been fulfilled by you - the business owner or your vendors.
The fulfillments API allows you to query fulfillment information based on multiple query parameters to meet your business requirements.
What made this section unhelpful for you?
Retrieve a list of fulfillments
List all fulfillments associated with the shop resource.
Title | Required? | Type | Description | Min Length | Max Length |
start | false | date | Start fetching fulfillments from order date (GMT). Format: YYYY-MM-DD E.g.: 2022-01-25 | ||
end | false | date | End fetching fulfillments to order date (GMT). Format: YYYY-MM-DD E.g.: 2022-06-30 | ||
vendorId | false | string | Filter payouts only for a specific vendor by | ||
fulfillment | false | string | Whether the payout item has been fulfilled or not. Possible values: fulfilled/unfulfilled | ||
offset | false | integer | The record count where the next result will start | ||
limit | false | integer | Max: 100 |
Header Parameters
Response
Response Attributes
Show child attributes
What made this section unhelpful for you?
Response
{
"total": 19,
"nextOffset": 12,
"fulfillments": [
{
"_id": "6201688080fb042fb4cb5245",
"vendorId": "6197e543b4423276a88f1f3a",
"vendorName": "partners-demo",
"lineItemName": "Classic Leather Jacket",
"lineItemVariant": "",
"lineItemSku": "CLJ",
"orderNumber": 46647,
"orderName": "#PV46647",
"date": "2022-02-07T17:55:13.000Z",
"lineItemVariantImage": "https://cdn.shopify.com/s/files/1/0280/1444/4592/products/leather-jacket-and-tea_925x_ccc1adaa-66a8-4623-a474-b0190c20c13a.jpg?v=1622052384",
"fulfillment": {
"fulfillmentId": 3701656748080,
"status": "success",
"createdAt": "2022-02-07T17:56:53Z",
"updatedAt": "2022-02-07T18:44:12Z",
"service": "manual",
"trackingCompany": "FSC",
"shipmentStatus": {},
"locationId": 34638299184,
"trackingNumber": "wrtygdsfhs",
"trackingNumbers": [
"wrtygdsfhs"
],
"trackingUrl": "https://tms.futuresupplychains.com/GUI/Tracking_New/Website/DocketTrack.aspx?st_Docnolist=wrtygdsfhs",
"trackingUrls": [
"https://tms.futuresupplychains.com/GUI/Tracking_New/Website/DocketTrack.aspx?st_Docnolist=wrtygdsfhs"
],
"fulfillmentNumber": "#PV46647.2",
"graphqlFulfillmentId": "gid://shopify/Fulfillment/3701656748080"
},
"shippingAddress": {
"first_name": "Jane",
"address1": "123 Fake Street",
"phone": "777-777-7777",
"city": "Fakecity",
"zip": "K2P 1L4",
"province": "Ontario",
"country": "Canada",
"last_name": "Smith",
"address2": {},
"company": {},
"latitude": 45.4205513,
"longitude": -75.6929455,
"name": "Jane Smith",
"country_code": "CA",
"province_code": "ON"
},
"billingAddress": {
"first_name": "Jane",
"address1": "123 Fake Street",
"phone": "777-777-7777",
"city": "Fakecity",
"zip": "K2P 1L4",
"province": "Ontario",
"country": "Canada",
"last_name": "Smith",
"address2": {},
"company": {},
"latitude": 45.4205513,
"longitude": -75.6929455,
"name": "Jane Smith",
"country_code": "CA",
"province_code": "ON"
}
},
{
"_id": "6201688080fb042fb4cb5243",
"vendorId": "6157faecbebcf01bf49097da",
"vendorName": "vendor-78",
"lineItemName": "Chequered Red Shirt",
"lineItemVariant": "",
"lineItemSku": "SH30",
"orderNumber": 46647,
"orderName": "#PV46647",
"date": "2022-02-07T17:55:13.000Z",
"lineItemVariantImage": "https://cdn.shopify.com/s/files/1/0280/1444/4592/products/red-plaid-shirt_925x_6bf5ab7c-b669-4209-a9bd-12e488276a97.jpg?v=1622052392",
"fulfillment": {
"fulfillmentId": 3701656748080,
"status": "success",
"createdAt": "2022-02-07T17:56:53Z",
"updatedAt": "2022-02-07T18:44:12Z",
"service": "manual",
"trackingCompany": "FSC",
"shipmentStatus": {},
"locationId": 34638299184,
"trackingNumber": "wrtygdsfhs",
"trackingNumbers": [
"wrtygdsfhs"
],
"trackingUrl": "https://tms.futuresupplychains.com/GUI/Tracking_New/Website/DocketTrack.aspx?st_Docnolist=wrtygdsfhs",
"trackingUrls": [
"https://tms.futuresupplychains.com/GUI/Tracking_New/Website/DocketTrack.aspx?st_Docnolist=wrtygdsfhs"
],
"fulfillmentNumber": "#PV46647.2",
"graphqlFulfillmentId": "gid://shopify/Fulfillment/3701656748080"
},
"shippingAddress": {
"first_name": "Jane",
"address1": "123 Fake Street",
"phone": "777-777-7777",
"city": "Fakecity",
"zip": "K2P 1L4",
"province": "Ontario",
"country": "Canada",
"last_name": "Smith",
"address2": {},
"company": {},
"latitude": 45.4205513,
"longitude": -75.6929455,
"name": "Jane Smith",
"country_code": "CA",
"province_code": "ON"
},
"billingAddress": {
"first_name": "Jane",
"address1": "123 Fake Street",
"phone": "777-777-7777",
"city": "Fakecity",
"zip": "K2P 1L4",
"province": "Ontario",
"country": "Canada",
"last_name": "Smith",
"address2": {},
"company": {},
"latitude": 45.4205513,
"longitude": -75.6929455,
"name": "Jane Smith",
"country_code": "CA",
"province_code": "ON"
}
}
]
}What made this section unhelpful for you?
Create a fulfillment
Creates a fulfillment associated with an order.
Title | Required? | Type | Description | Min Length | Max Length |
trackingNumber | true | string | Unique tracking number provided by your shippingCarrier e.g.: GM99999999999 | ||
trackingUrl | true | string | Tracking URL for the order items | ||
shippingCarrier | true | string | Shipping Carrier/Tracking Company options. The list found at https://shopify.dev/api/admin-rest/2021-10/resources/fulfillment | ||
lineItemsToFulfill | true | array | lineItems _id to fulfill can be found at list fulfillment items |
Header Parameters
Body Parameters
Response
Response Attributes
What made this section unhelpful for you?
Response
{
"fulfillments": [
{
"type": "success",
"itemId": "629120f34052dd0f140bdfb5",
"message": "Fulfillment completed successfully."
}
]
}
OR
{
"fulfillments": [
{
"type": "error",
"itemId": "6291235245c5dd0f9d9a468f",
"message": {
"base": [
"Line item '10995002671152' is already fulfilled"
]
}
}
]
}What made this section unhelpful for you?
Commissions
represent the money you keep for your services or profit before sending the payouts to your business partners, drop shippers, artists, and consignors.
The commissions API allows you to query all commission information based on your vendors or skus.