Item API Reference

Discover how to create, retrieve, update, and manage items effortlessly using our intuitive Item model. Explore the robust API endpoints and data structures available to streamline your inventory management process. Whether you're selling products, services, or digital goods, this guide equips you with the tools and knowledge to optimize your item management workflow.

The Item model

Items are cataloged products or services with essential details like name, price, unit, and description. These items play a pivotal role in creating estimates and invoices, offering businesses a standardized way to include products or services in their financial documents. This ensures accuracy, consistency, and efficiency in managing and presenting offerings to clients during the estimation and invoicing processes.

Properties

Name
id
Type
string
Description
Unique identifier for the item.
Name
name
Type
string
Description
Name of the item.
Name
description
Type
string
Description
Description of the item.
Name
price
Type
integer
Description
Price of the item in cents.
Name
unit_id
Type
string
Description
ID of the unit.
Name
business_id
Type
string
Description
ID of the business.
Name
created_at
Type
integer
Description
Unix timestamp when the item was created.
Name
updated_at
Type
integer
Description
Unix timestamp when the item was last updated.
Name
tax_per_item_enabled
Type
boolean
Description
Indicates whether the item has taxes.
Name
unit
Type
object
Description
Unit object.

GETapi/v2/items

List all items

This endpoint allows you to retrieve a paginated list of all your items.

Parameters

Name
limit
Type
integer
Description
A limit on the number of items to be returned on a single page.
Name
page
Type
integer
Description
Page number (for pagination).
Name
price
Type
integer
Description
Filter records by price.
Name
unit_id
Type
integer
Description
Filter records by unit_id.
Name
name
Type
string
Description
Filter records by name.

Request

GET

api/v2/items

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/items" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": [
    {
      "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
      "name": "Professional Consultation",
      "description": "One-hour professional consultation on business strategy",
      "price": 200,
      "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "created_at": 1683018952,
      "updated_at": 1683279136,
      "tax_per_item_enabled": false,
      "unit": {
        "id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
        "name": "hour",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
      }
    },
    {
      "id": "9911d504-bb27-4a7a-a389-1155ceacc135",
      "name": "Website Development",
      "description": "Custom website development including frontend and backend",
      "price": 5000,
      "unit_id": "9abe2330-34fd-43ba-b7ed-e9f0989f1d5c",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "created_at": 1683018673,
      "updated_at": 1683018673,
      "tax_per_item_enabled": false,
      "unit": {
        "id": "9abe2330-34fd-43ba-b7ed-e9f0989f1d5c",
        "name": "project",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
      }
    }
  ]
}

POSTapi/v2/items

Create an item

This endpoint allows you to create new item.

Parameters

Name
name
Type
string
Description
Name of the item.
Name
price
Type
integer
Description
Price of item in cents.

Optional Parameters

Name
unit_id
Type
integer
Description
ID of unit.
Name
description
Type
string
Description
Description of item.
Name
tax_per_item_enabled
Type
boolean
Description
Pass true if item has taxes.
Name
tax_type_ids
Type
array
Description
Pass an array of tax type IDs that need to be attached with this item.

Request

POST

api/v2/items

curl --request POST \
  "https://payments.your-domain.com/api/v2/items" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"Laptop\",
    \"price\": \"10000\",
    \"unit_id\": \"9ab7ea71-6413-4d6b-b444-ebfc0f53e225\",
    \"description\": \"New Laptop with latest features\"
  }"

Response

{
  "data": {
    "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
    "name": "Laptop",
    "description": "New Laptop with latest features",
    "price": 10000,
    "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1683018952,
    "updated_at": 1683279136,
    "tax_per_item_enabled": false,
    "unit": {
      "id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
      "name": "hour",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    }
  }
}

GETapi/v2/items/{id}

Retrieve an item

This endpoint allows you to retrieve an item.

Parameters

Name
id
Type
integer
Description
ID of the item.

Request

GET

api/v2/items/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/items/9911d6af-02ee-40dd-b8da-95df7301bd18" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": {
    "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
    "name": "Laptop",
    "description": "New Laptop with latest features",
    "price": 10000,
    "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1683018952,
    "updated_at": 1683279136,
    "tax_per_item_enabled": false,
    "unit": {
      "id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
      "name": "hour",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    }
  }
}

PUTapi/v2/items/{id}

Update an item

This endpoint allows you to perform an update on an item.

Parameters

Name
id
Type
integer
Description
The ID of the item.
Name
name
Type
string
Description
Name of the item.
Name
price
Type
integer
Description
Price of item in cents.

Optional Parameters

Name
unit_id
Type
string
Description
ID of unit.
Name
description
Type
string
Description
Description of item
Name
tax_per_item_enabled
Type
boolean
Description
Pass true if item has taxes.
Name
tax_type_ids
Type
array
Description
Array of tax type IDs that need to be attach with this item.

Request

PUT

api/v2/items/{id}

curl --request PUT \
  "https://payments.your-domain.com/api/v2/items/9911d6af-02ee-40dd-b8da-95df7301bd18" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"Laptop\",
    \"price\": \"10000\",
    \"unit_id\": \"9ab7ea71-6413-4d6b-b444-ebfc0f53e225\",
    \"description\": \"New Laptop with latest features\"
  }"

Response

{
  "data": {
    "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
    "name": "Laptop",
    "description": "New Laptop with latest features",
    "price": 10000,
    "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1683018952,
    "updated_at": 1683279136,
    "tax_per_item_enabled": false,
    "unit": {
      "id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
      "name": "hour",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    }
  }
}

DELETEapi/v2/items/{id}

Delete item

This endpoint allows you to delete a specific Item.

Parameters

Name
id
Type
integer
Description
The ID of the item.

Request

DELETE

api/v2/items/{id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v2/items/9911d6af-02ee-40dd-b8da-95df7301bd18" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
  "object": "Item",
  "deleted": true
}

GETapi/v2/item-units

List all item units

This endpoint allows you to retrieve a paginated list of all your item units.

Parameters

Name
limit
Type
integer
Description
A limit on the number of item units to be returned on a single page.
Name
page
Type
integer
Description
Page number (for pagination).
Name
name
Type
string
Description
Filter records by name.

Request

GET

api/v2/item-units

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/item-units" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": [
    {
      "id": "9abdfce7-3424-4199-8a9a-d0b272f71ea2",
      "name": "box",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    },
    {
      "id": "9abdfce7-3857-4e6e-9212-34e91dc4dae2",
      "name": "kg",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
    },
  ]
}

POSTapi/v2/item-units

Create an item unit

This endpoint allows you to create a new item unit.

Parameters

Name
name
Type
string
Description
Name of the item unit.

Request

POST

api/v2/item-units

curl --request POST \
  "https://payments.your-domain.com/api/v2/item-units" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"gallon\"
  }"

Response

{
  "data": {
    "id": "9abe0db9-f1c1-41a6-9b97-6335206a1b88",
    "name": "gallon",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  }
}

GETapi/v2/item-units/{id}

Retrieve an item unit

This endpoint allows you to retrieve an item unit.

Parameters

Name
id
Type
integer
Description
ID of the item unit.

Request

GET

api/v2/item-units/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v2/item-units/9abe0db9-f1c1-41a6-9b97-6335206a1b88" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "data": {
    "id": "9abe0db9-f1c1-41a6-9b97-6335206a1b88",
    "name": "gallon",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  }
}

PUTapi/v2/item-units/{id}

Update an item unit

This endpoint allows you to perform an update on an item unit.

Parameters

Name
id
Type
integer
Description
The ID of the item unit.
Name
name
Type
string
Description
Name of the item unit.

Request

PUT

api/v2/item-units/{id}

curl --request PUT \
  "https://payments.your-domain.com/api/v2/item-units/9abe0db9-f1c1-41a6-9b97-6335206a1b88" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"mm\"
  }"

Response

{
  "data": {
    "id": "9abe0db9-f1c1-41a6-9b97-6335206a1b88",
    "name": "mm",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d"
  }
}

DELETEapi/v2/item-units/{id}

Delete item unit

This endpoint allows you to delete a specific Item unit.

Parameters

Name
id
Type
integer
Description
The ID of the item unit.

Request

DELETE

api/v2/item-units/{id}

curl --request DELETE \
  "https://payments.your-domain.com/api/v2/item-units/9abe0db9-f1c1-41a6-9b97-6335206a1b88" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "id": "9abe0db9-f1c1-41a6-9b97-6335206a1b88",
  "object": "Unit",
  "deleted": true
}