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
    Field Type
    Description

    Unique identifier for the item.

  • Name
    name
    Type
    string
    Field Type
    Description

    Name of the item.

  • Name
    description
    Type
    string
    Field Type
    Description

    Description of the item.

  • Name
    price
    Type
    integer
    Field Type
    Description

    Price of the item in cents.

  • Name
    unit_id
    Type
    string
    Field Type
    Description

    ID of the unit.

  • Name
    business_id
    Type
    string
    Field Type
    Description

    ID of the business.

  • Name
    creator_id
    Type
    string
    Field Type
    Description

    ID of the user who created the item.

  • Name
    created_at
    Type
    timestamp
    Field Type
    Description

    Unix timestamp when the item was created.

  • Name
    updated_at
    Type
    timestamp
    Field Type
    Description

    Unix timestamp when the item was updated.

  • Name
    updated_at
    Type
    timestamp
    Field Type
    Description

    Unix timestamp when the item was last updated.

  • Name
    tax_per_item_enabled
    Type
    boolean
    Field Type
    Description

    Indicates whether the item has taxes.

  • Name
    unit
    Type
    object
    Field Type
    Description

    Unit object.

GETapi/v1/items

List all items

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

Query Parameters

  • Name
    limit
    Type
    integer
    Field Type
    optional
    Description

    A limit on the number of items to be returned. (default is 10)

  • Name
    page
    Type
    integer
    Field Type
    optional
    Description

    Page number for pagination. (default is 1)

  • Name
    name
    Type
    string
    Field Type
    optional
    Description

    Filter records by name.

  • Name
    unit_id
    Type
    string
    Field Type
    optional
    Description

    Filter records by unit_id.

  • Name
    price
    Type
    integer
    Field Type
    optional
    Description

    Filter records by price.

Request

GET
api/v1/items
curl --request GET \
  --get "https://payments.your-domain.com/api/v1/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",
      "price": 200,
      "description": "One-hour professional consultation on business strategy",
      "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
      "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",
      "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
      "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/v1/items

Create an item

This endpoint allows you to create new item.

Body Parameters

  • Name
    name
    Type
    string
    Field Type
    required
    Description

    Name of the item.

  • Name
    price
    Type
    integer
    Field Type
    required
    Description

    Price of item in cents.

  • Name
    unit_id
    Type
    integer
    Field Type
    optional
    Description

    ID of unit.

  • Name
    description
    Type
    string
    Field Type
    optional
    Description

    Description of item.

  • Name
    tax_per_item_enabled
    Type
    boolean
    Field Type
    optional
    Description

    Pass true if item has taxes.

  • Name
    tax_type_ids
    Type
    array
    Field Type
    optional
    Description

    Pass an array of tax type IDs that need to be attached with this item.

Request

POST
api/v1/items
curl --request POST \
  "https://payments.your-domain.com/api/v1/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",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "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"
    },
    "taxes": []
  }
}
GETapi/v1/items/{id}

Retrieve an item

This endpoint allows you to retrieve an item.

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    ID of the item.

Request

GET
api/v1/items/{id}
curl --request GET \
  --get "https://payments.your-domain.com/api/v1/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",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "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/v1/items/{id}

Update an item

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

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    The ID of the item.

Body Parameters

  • Name
    name
    Type
    string
    Field Type
    optional
    Description

    Name of the item.

  • Name
    price
    Type
    integer
    Field Type
    optional
    Description

    Price of item in cents.

  • Name
    unit_id
    Type
    string
    Field Type
    optional
    Description

    ID of unit.

  • Name
    description
    Type
    string
    Field Type
    optional
    Description

    Description of item

  • Name
    tax_per_item_enabled
    Type
    boolean
    Field Type
    optional
    Description

    Pass true if item has taxes.

  • Name
    tax_type_ids
    Type
    array
    Field Type
    optional
    Description

    Array of tax type IDs that need to be attach with this item.

Request

PUT
api/v1/items/{id}
curl --request PUT \
  "https://payments.your-domain.com/api/v1/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\": \"Apple Macbook\",
    \"price\": \"10000\",
    \"unit_id\": \"9ab7ea71-6413-4d6b-b444-ebfc0f53e225\",
    \"description\": \"Light and powerful laptop\"
  }"

Response

{
  "data": {
    "id": "9911d6af-02ee-40dd-b8da-95df7301bd18",
    "name": "Apple Macbook",
    "description": "Light and powerful laptop",
    "price": 10000,
    "unit_id": "9ab7ea71-6413-4d6b-b444-ebfc0f53e225",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "creator_id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "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/v1/items/{id}

Delete item

This endpoint allows you to delete a specific Item.

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    The ID of the item.

Request

DELETE
api/v1/items/{id}
curl --request DELETE \
  "https://payments.your-domain.com/api/v1/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/v1/item-units

List all item units

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

Query Parameters

  • Name
    limit
    Type
    integer
    Field Type
    optional
    Description

    A limit on the number of item units to be returned. (default is 5)

  • Name
    page
    Type
    integer
    Field Type
    optional
    Description

    Page number for pagination. (default is 1)

  • Name
    name
    Type
    string
    Field Type
    optional
    Description

    Filter records by name.

Request

GET
api/v1/item-units
curl --request GET \
  --get "https://payments.your-domain.com/api/v1/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/v1/item-units

Create an item unit

This endpoint allows you to create a new item unit.

Body Parameters

  • Name
    name
    Type
    string
    Field Type
    required
    Description

    Name of the item unit.

Request

POST
api/v1/item-units
curl --request POST \
  "https://payments.your-domain.com/api/v1/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/v1/item-units/{id}

Retrieve an item unit

This endpoint allows you to retrieve an item unit.

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    ID of the item unit.

Request

GET
api/v1/item-units/{id}
curl --request GET \
  --get "https://payments.your-domain.com/api/v1/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/v1/item-units/{id}

Update an item unit

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

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    The ID of the item unit.

Body Parameters

  • Name
    name
    Type
    string
    Field Type
    optional
    Description

    Name of the item unit.

Request

PUT
api/v1/item-units/{id}
curl --request PUT \
  "https://payments.your-domain.com/api/v1/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/v1/item-units/{id}

Delete item unit

This endpoint allows you to delete a specific Item unit.

URL Parameters

  • Name
    id
    Type
    string
    Field Type
    required
    Description

    The ID of the item unit.

Request

DELETE
api/v1/item-units/{id}
curl --request DELETE \
  "https://payments.your-domain.com/api/v1/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
}