PuppetVendors Documentation

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.

Production:

https://api.puppetvendors.com/

PuppetVendors API uses the following status or error codes.

The API rate limit is 100 requests per minute.

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.

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

Content-Typestring

Body Parameters

apiKeystring

shopDomainstring

Response

200

Object

Response Attributes

tokenstring

shopDomainstring

400

Object

Response Attributes

errorstring

401

Object

Response Attributes

errorstring

422

Object

Response Attributes

errorstring

curl --location 'https://api.puppetvendors.com/v1/authenticate/' \
--header 'Content-Type: application/json' \
--data '{
  "apiKey": "63ed2a8863e8f7af5861ab9f4ae9617fe5cb9705287296a97ff9bf5c854eb0603fce1f4daa1d3c62b3819d1c65156e35",
  "shopDomain": "lilydale-3.myshopify.com"
}'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU0NTA4NDE0LCJleHAiOjE2NTQ1OTQ4MTR9.y7sXXNGgo32HphvaZnpv2u3vlm6BVzBQzFTDNKUTpAk",
  "shopDomain": "lilydale-3.myshopify.com"
}

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.

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.

List all users associated with the shop resource.

Header Parameters

Content-Typestring

x-access-tokenstring

Response

200

Object

Response Attributes

usersarray

Show child attributes

1
2
3

curl --location 'https://api.puppetvendors.com/v1/users' \
--header 'Content-Type: application/json' \
--header 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU1MzY5MTAwLCJleHAiOjE2NTU0NTU1MDB9.DJ5Rn4axhOZeRuPh7uVcmqn6nwMlNNNBVkVvYNVqbt8'

{
  "users": [
    {
      "userId": "62a8b4347aaa2b1e7aafe131",
      "vendorId": "6157faecbebcf01bf49097d9",
      "vendorName": "Vendor 1",
      "createdAt": "2022-06-14T16:15:48.000Z",
      "email": "support@puppetvendors.com"
    },
    {
      "userId": "62a8b4397aaa2b1e7aafe132",
      "vendorId": "6157faecbebcf01bf49097d9",
      "vendorName": "Vendor 2",
      "createdAt": "2022-06-14T16:15:53.000Z",
      "email": "support@puppetvendors.com"
    }
  ]
}

Creates a new user associated with a vendor resource.

Title	Required?	Type	Description	Min Length	Max Length
vendorId	true	string	A unique vendorId. This user will have access to this vendor's information.
email	true	string	The user's email address used for logging into the vendor portal.
password	true	string	The user's password used for logging into the vendor portal.

Header Parameters

Content-Typestring

x-access-tokenstring

Body Parameters

vendorIdstring

emailstring

passwordstring

Response

200

Object

Response Attributes

messagestring

userobject

Show child attributes

curl --location 'https://api.puppetvendors.com/v1/users' \
--header 'Content-Type: application/json' \
--header 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU1MjIxNjUxLCJleHAiOjE2NTUzMDgwNTF9.F-RZLVzNNlNH5cKwO96R86wW-Yq1YTE8CbxtbfhOZ_U' \
--data '{
  "vendorId": "vendorId",
  "email": "email",
  "password": "password"
}'

{
  "message": "User created successfully.",
  "user": {
    "vendor": {},
    "type": "vendor",
    "approved": true,
    "_id": "62a8b4397aaa2b1e7aafe132",
    "shopId": "6157faddbebcf01bf49097d8",
    "vendorId": "6157faecbebcf01bf49097d9",
    "email": "support@puppetvendors.com",
    "password": "$2a$12$oT3PvJASHp/asAKhZVPAreTdUESbGSL0hQgY3DMkxH1sk7R1MtZp6",
    "invitationDate": "2022-06-14T16:15:53.000Z",
    "updatedAt": "2022-06-14T16:15:53.000Z",
    "createdAt": "2022-06-14T16:15:53.000Z",
    "__v": 0
  }
}

List a specific user based on the userId associated with the vendor resource.

Parameters

Title	Required?	Type	Description	Min Length	Max Length
:userId	true	String	The user's unique id you want to retrieve.

Header Parameters

Content-Typestring

x-access-tokenstring

Response

200

Object

Response Attributes

vendorstring

typestring

approvedboolean

_idstring

shopIdstring

vendorIdstring

emailstring

profileobject

Show child attributes

invitationDatestring

updatedAtstring

createdAtstring

__vnumber

400

Object

Response Attributes

errorstring

422

Object

Response Attributes

errorstring

1
2
3

curl --location 'https://api.puppetvendors.com/v1/users/:userId' \
--header 'Content-Type: application/json' \
--header 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU1MzY5MTAwLCJleHAiOjE2NTU0NTU1MDB9.DJ5Rn4axhOZeRuPh7uVcmqn6nwMlNNNBVkVvYNVqbt8'

{
  "vendor": "partner demo",
  "type": "vendor",
  "approved": true,
  "_id": "617192c81bbacc29073f837c",
  "shopId": "6157faddbebcf01bf49097d8",
  "vendorId": "6157faecbebcf01bf49097d9",
  "email": "string",
  "profile": {
    "Contact Full Name": "Kriangsak khanijomdi",
    "Business Name": "Refinitiv",
    "Biz Name": "DDDDDD",
    "GST Id": false,
    "Random Custom 1": "Rando1",
    "Random Custom 2": "Rando12",
    "businessAddress": {
      "address1": "LORONG 22 GEYLANG",
      "address2": "1",
      "city": "Singapore",
      "state": "State",
      "postalCode": "398664",
      "country": "Singapore"
    }
  },
  "invitationDate": "2021-10-21T16:18:16.000Z",
  "updatedAt": "2021-10-21T16:18:16.000Z",
  "createdAt": "2021-10-21T16:18:16.000Z",
  "__v": 0
}

Updates information for a specific vendor associated with the shop resource.

Parameters

Title	Required?	Type	Description	Min Length	Max Length
:userId	true	String	The user's unique id you want to update.

Title	Required?	Type	Description	Min Length	Max Length
email	true	string	The user's email address used for logging into the vendor portal.
password	true	string	The user's password used for logging into the vendor portal.

Header Parameters

Content-Typestring

x-access-tokenstring

Body Parameters

emailstring

passwordstring

Response

200

Object

Response Attributes

messagestring

userobject

Show child attributes

curl --location --request PUT 'https://api.puppetvendors.com/v1/users/:userId' \
--header 'Content-Type: application/json' \
--header 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU1NDMyNjU0LCJleHAiOjE2NTU1MTkwNTR9.9FsBTHUeJ7sOZJr0QzmjKol6ShgYC1ERKwNiOBLF3Nw' \
--data '{
  "email": "email",
  "password": "password"
}'

{
  "message": "User updated successfully.",
  "user": {
    "vendor": "partner demo",
    "type": "vendor",
    "approved": true,
    "_id": "617192c81bbacc29073f837c",
    "shopId": "6157faddbebcf01bf49097d8",
    "vendorId": "6157faecbebcf01bf49097d9",
    "email": "updatedemail@puppetvendors.com",
    "password": "$2a$12$McA35TJcHMOYRvOIyjKqFe7OTyYhraAHMXFTzWS2dMCExsOW7D9l6",
    "profile": {
      "Contact Full Name": "Kriangsak khanijomdi",
      "Business Name": "Refinitiv",
      "Biz Name": "DDDDDD",
      "GST Id": false,
      "Random Custom 1": "Rando1",
      "Random Custom 2": "Rando12",
      "businessAddress": {
        "address1": "LORONG 22 GEYLANG",
        "address2": "1",
        "city": "Singapore",
        "state": "State",
        "postalCode": "398664",
        "country": "Singapore"
      }
    },
    "invitationDate": "2021-10-21T16:18:16.000Z",
    "updatedAt": "2021-10-21T16:18:16.000Z",
    "createdAt": "2021-10-21T16:18:16.000Z"
  }
}

Deletes a user using the user's unique userId.

Deleting a user will disable the ability for them to log into the vendor portal.

Parameters

Title	Required?	Type	Description	Min Length	Max Length
:userId	true	String	The user's unique id you want to delete.

Header Parameters

Content-Typestring

x-access-tokenstring

Response

200

Object

Response Attributes

messagestring

userobject

Show child attributes

400

Object

Response Attributes

errorstring

422

Object

Response Attributes

errorstring

1
2
3

curl --location --request DELETE 'https://api.puppetvendors.com/v1/users/:userId' \
--header 'Content-Type: application/json' \
--header 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MTU3ZmFkZGJlYmNmMDFiZjQ5MDk3ZDgiLCJzaG9wRG9tYWluIjoibGlseWRhbGUtMy5teXNob3BpZnkuY29tIiwic2hvcE5hbWUiOiJsaWx5ZGFsZS0zIiwiZW1haWwiOiJzdXBwb3J0QHB1cHBldHZlbmRvcnMuY29tIiwic2hvcE93bmVyIjoiUHVwcGV0IFZlbmRvcnMiLCJzaG9wUGhvbmUiOiI4MjI4MDgwMyIsInNob3BDb3VudHJ5IjoiU2luZ2Fwb3JlIiwic2hvcENpdHkiOiJTaW5nYXBvcmUiLCJzaG9wQ3VycmVuY3kiOiJTR0QiLCJzaG9wVGltZXpvbmUiOiJBbWVyaWNhL05ld19Zb3JrIiwiaWF0IjoxNjU1MjIxNjUxLCJleHAiOjE2NTUzMDgwNTF9.F-RZLVzNNlNH5cKwO96R86wW-Yq1YTE8CbxtbfhOZ_U'

{
  "message": "User deleted successfully.",
  "user": {
    "vendor": "partner demo",
    "type": "vendor",
    "approved": true,
    "_id": "617192c81bbacc29073f837c",
    "shopId": "6157faddbebcf01bf49097d8",
    "vendorId": "6157faecbebcf01bf49097d9",
    "email": "updatedemail@puppetvendors.com",
    "password": "$2a$12$McA35TJcHMOYRvOIyjKqFe7OTyYhraAHMXFTzWS2dMCExsOW7D9l6",
    "profile": {
      "Contact Full Name": "Kriangsak khanijomdi",
      "Business Name": "Refinitiv",
      "Biz Name": "DDDDDD",
      "GST Id": false,
      "Random Custom 1": "Rando1",
      "Random Custom 2": "Rando12",
      "businessAddress": {
        "address1": "LORONG 22 GEYLANG",
        "address2": "1",
        "city": "Singapore",
        "state": "State",
        "postalCode": "398664",
        "country": "Singapore"
      }
    },
    "invitationDate": "2021-10-21T16:18:16.000Z",
    "updatedAt": "2021-10-21T16:18:16.000Z",
    "createdAt": "2021-10-21T16:18:16.000Z",
    "__v": 0
  }
}

The reports API allows you to query vendor-specific order information to generate reports to your needs.

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.

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.

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.

Sections

Introduction

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

What made this section unhelpful for you?

Errors

What made this section unhelpful for you?

Status Codes

What made this section unhelpful for you?

Authentication

Header Parameters

Body Parameters

Response

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response

Vendors

Users

What made this section unhelpful for you?

Retrieve a list of users

Header Parameters

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Create a user

Header Parameters

Body Parameters

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Retrieve a specific user

Parameters

Header Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Update a user

Parameters

Header Parameters

Body Parameters

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Delete a user

Parameters

Header Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Reports

Payouts

Fulfillments

Commissions

Response

Response

Response

Response

Response