Vendors

Vendors in Kojo represent the external business entities your business buys goods and services from. They are concepually synonomous with the concept of Vendors in many accounting systems (Spectrum, QuickBooks, etc.). An additional nuance to the concept of Vendors in Kojo are Vendor Contacts, who are specific contacts at the vendor organization.

Vendor Schema

Vendor

Name	Type	Description	Example
id	ID	Unique identifier for orders	"ckmnpybisiy5x08abky4g2d1f"
name	string	User defined name for the vendor	"Dunder Mifflin"
code	string	Vendor Code	"ACE123"
location	Location	The location associated with this vendor	See Location docs
createdAt	dateTime	When this object was created	"2021-03-24 17:26:46.983Z"
deletedAt	dateTime	When this object was deleted	"2021-03-24 17:26:46.983Z"
updatedAt	dateTime	When this object was last updated	"2021-03-24 17:26:46.983Z"

REST Endpoints

GET /vendors

Gets a list of all vendors

Parameters

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, name, id, updatedAt.

Allowed filter fields: code, createdAt, id, name, updatedAt.

Response

A list of Vendor objects

Example Request

GET https://api.kojo.tech/vendors

Example Response

[
  {
    "code": "HOM001",
    "createdAt": "2021-03-24 17:26:46.983Z",
    "deletedAt": null,
    "name": "Home Depot",
    "id": "ckmnpybixiy5y0817spfhmj78",
      "location": {
        "id": "ckpiv3ks200au0976bq78ksv6",
        "name": "1 West 3rd St.",
        "addressLine1": "1 West 3rd St.",
        "addressLine2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zipcode": "90018"
    },
    "updatedAt": "2021-03-24 17:26:46.983Z"
  },
  {
    "code": "A1F001",
    "createdAt": "2021-06-04T21:51:06.402Z",
    "deletedAt": "2021-10-03T21:52:16.262Z",
    "id": "ckpiv3ksafd2v0976k2bsuuju",
    "name": "A1 Fence Company",
    "location": {
      "id": "ckpiv3ksn0kk09976n96gl6u5",
        "name": "2831 E. La Cresta Ave.",
        "addressLine1": "2831 E. La Cresta Ave.",
        "addressLine2": "",
        "city": "Anaheim",
        "state": null,
        "zipcode": "92806"
    },
    "updatedAt": "2021-10-03T21:52:16.262Z"
  },
]

POST /vendors

Creates a single vendor

Parameters

Name	Type	Description	Example
code	string	Vendor Code	"ACE123"
name	string	User defined name for the vendor	"Dunder Mifflin"

Response

The created Vendor object

Example Request

POST https://api.kojo.tech/vendors
{
  "code": "ACE123",
  "name": "Vendor Name"
}

Example Response

{
    "code": "ACE123",
    "createdAt": "2021-06-11T20:19:27.812Z",
    "deletedAt": null,
    "id": "ckpsrwon9000k0976h8icqhvm",
    "name": "Vendor Name",
    "updatedAt": "2021-06-11T20:19:27.812Z"
}

POST /vendors/batch

warning

Batch endpoints will accept at most 1000 elements per request.

Creates or Updates multiple Vendors at once.

Parameters

Name	Type	Description
inputs	UpsertVendorInput[]	A list of vendors

UpsertVendorInput

Name	Type	Description	Example
code	string	Code of the vendor to update. If both id and code are provided, the vendor's code will be updated to this value.	"ACE123"
name	string	User defined name for the vendor	"Dunder Mifflin"

Response

A list of Vendors.

Example Mutation

POST https://api.kojo.tech/vendors
[
  {
    "code": "ACE123",
    "name": "Vendor Name"
  }
]

Example Response

[
  {
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "code": "ACE123",
    "name": "Dunder Mifflin (edited)"
  }
]

GET /vendors/:idOrCode

Gets a single vendor based on the provided id or code

Parameters

Name	Type	Description	Example
id	string	Vendor id	"ckpsrwon9000k0976h8icqhvm"
code	string	Vendor Code	"ACE123"

One of id or code must provided in the URL

Response

The specified Vendor object

Example Request

GET https://api.kojo.tech/vendors/ACE123

Example Response

{
    "code": "ACE123",
    "createdAt": "2021-06-11T20:19:27.812Z",
    "deletedAt": null,
    "id": "ckpsrwon9000k0976h8icqhvm",
    "name": "Vendor Name",
    "updatedAt": "2021-06-11T20:19:27.812Z"
}

PATCH /vendors/:idOrCode

Updates a single vendor

Parameters

Name	Type	Description	Example
id	ID	ID of the vendor to update	"ckmnpybisiy5x08abky4g2d1f"
code	string	Code of the vendor to update. If both id and code are provided, the vendor's code will be updated to this value.	"ACE123"
name	string	New name for vendor	"Updated Name"

One of id or code must provided in the URL

Response

The updated Vendor object

Example Request

PATCH https://api.kojo.tech/vendors/ACE123
{
  "name": "Updated name"
}

Example Response

{
    "code": "ACE123",
    "createdAt": "2021-06-11T20:19:27.812Z",
    "deletedAt": null,
    "id": "ckpsrwon9000k0976h8icqhvm",
    "name": "Updated name",
    "updatedAt": "2021-06-11T20:19:27.812Z"
}

DELETE /vendors/:idOrCode

Deletes a single vendor

Example Request

DELETE https://api.kojo.tech/vendors/ACE123

Example Response

{
    "code": "ACE123",
    "createdAt": "2021-06-11T20:19:27.812Z",
    "id": "ckpsrwon9000k0976h8icqhvm",
    "name": "Updated name",
    "updatedAt": "2021-06-11T20:19:27.812Z",
    "deletedAt": "2021-06-11T20:19:27.812Z"
}

POST /vendors/:idOrCode/location

Attaches a location to the vendor specified in the URL

Parameters

Name	Type	Description	Example
id	ID	Vendor id	"ckpsrwon9000k0976h8icqhvm"
code	string	Vendor Code	"ACE123"
locationId	ID	ID of the location	"fakjrwon89jkk0976h8ic41da"

One of id or code must provided in the URL

Response

The updated Vendor object

Example Request

POST https://api.kojo.tech/vendors/ACE123/location
{
  "locationId": "fakjrwon89jkk0976h8ic41da"
}

Example Response

{
  "code": "ACE123",
  "createdAt": "2021-06-04T21:51:06.402Z",
  "deletedAt": null,
  "id": "ckpsrwon9000k0976h8icqhvm",
  "name": "Vendor Name",
  "updatedAt": "2021-06-04T21:52:16.262Z",
  "location": {
      "id": "fakjrwon89jkk0976h8ic41da",
      "name": "2831 E. La Cresta Ave.",
      "addressLine1": "2831 E. La Cresta Ave.",
      "addressLine2": "",
      "city": "Anaheim",
      "state": null,
      "zipcode": "92806"
  }
}