Invoice Items

Version: 3.0.0

Generate an API Key for the Invoice channel before making requests.

Invoice items are the individual products or services you bill for. Create reusable item templates once, then add them to any invoice. Each item stores a name, rate, category, and description.

Reusable invoice items save time and ensure consistent pricing across all invoices. Create them once, reference them in multiple invoices.

Every create and list response returns two identifiers: a display item_id (a short sequence number) and a data_id (an encrypted token). Always send the data_id token when updating, activating, deactivating, deleting, fetching an item, or referencing the item inside an invoice. The item_id is for display only.

Available Operations

Action	Method	Endpoint	Description
Create Item	POST	`https://api.payorc.com/invoice/v1/items/add`	Create a new line item
Update Item	POST	`https://api.payorc.com/invoice/v1/items/update`	Modify item details
Deactivate	POST	`https://api.payorc.com/invoice/v1/items/deactivate`	Disable item (hide from new invoices)
Activate	POST	`https://api.payorc.com/invoice/v1/items/activate`	Re-enable a deactivated item
Delete	POST	`https://api.payorc.com/invoice/v1/items/delete`	Permanently remove an item
Get Details	GET	`https://api.payorc.com/invoice/v1/items/details`	Fetch a single item
List Items	GET	`https://api.payorc.com/invoice/v1/items/list`	List all items with pagination

Authentication

Header	Type	Description
`merchant-key`	String	Your merchant key
`merchant-secret`	String	Your merchant secret

Create Item

Create a new reusable line item for invoices.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/items/add`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`item_name`	String	Yes	Item name (1–50 characters, must be unique per merchant)
`item_rate_per_unit`	Number	Yes	Item rate per unit (greater than 0, max 9999999)
`item_category`	String	Yes	Item category (e.g., Electronics, Clothing, Services) (max 100 characters)
`item_description`	String	No	Item description (max 200 characters)

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/items/add \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "item_name": "Apple",
    "item_rate_per_unit": "1000",
    "item_category": "Fruits",
    "item_description": "This is the invoice item."
  }'

Example Response

{
  "data": {
    "item_id": "0000000001",
    "data_id": "VTVKMjhqUFdQQkN"
  },
  "message": "Item added successfully",
  "status": "success",
  "code": "00"
}

Item names must be unique within your merchant account. Attempting to create a duplicate will return an error. Store the returned data_id — it is the token you pass to all other item operations.

Update Item

Modify details of an existing invoice item. All fields except data_id follow the same rules as Create Item.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/items/update`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the item to update (from the create/list response)
`item_name`	String	Yes	Item name (1–50 characters)
`item_rate_per_unit`	Number	Yes	Rate per unit (greater than 0, max 9999999)
`item_category`	String	Yes	Item category (max 100 characters)
`item_description`	String	No	Item description (max 200 characters)

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/items/update \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "VTVKMjhqUFdQQkN",
    "item_name": "Keyboard",
    "item_rate_per_unit": "10000",
    "item_category": "Electronics",
    "item_description": "This is the invoice item."
  }'

Example Response

{
    "message": "Item updated successfully.",
    "status": "success",
    "code": "00"
}

Deactivate Item

Deactivate an item so it no longer appears when creating new invoices. Existing invoices using this item are unaffected.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/items/deactivate`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the item to deactivate

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/items/deactivate \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "VTVKMjhqUFdQQkN"
  }'

Example Response

{
    "message": "Item deactivated successfully.",
    "status": "success",
    "code": "00"
}

Deactivated items can be reactivated at any time. They are not deleted — just hidden from item selection.

Activate Item

Reactivate a previously deactivated item.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/items/activate`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the item to activate

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/items/activate \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "VTVKMjhqUFdQQkN"
  }'

Example Response

{
    "message": "Item activated successfully.",
    "status": "success",
    "code": "00"
}

Delete Item

Permanently delete an invoice item. This cannot be undone.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/items/delete`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the item to delete

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/items/delete \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "VTVKMjhqUFdQQkN"
  }'

Example Response

{
    "message": "Item deleted successfully.",
    "status": "success",
    "code": "00"
}

Deleting an item is permanent and cannot be undone. Existing invoices that reference this item will retain the data, but the item cannot be used in new invoices.

Get Item Details

Retrieve details for a single invoice item.

Endpoint

Method	URL
GET	`https://api.payorc.com/invoice/v1/items/details?data_id=DATA_ID`

Pass the encrypted data_id token (not the display item_id) as the query parameter. Please use the test credentials for sandbox testing.

Query Parameters

Parameter	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the item to fetch

Code Examples

curl -X GET "https://api.payorc.com/invoice/v1/items/details?data_id=VTVKMjhqUFdQQkN" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET"

Example Response

{
  "data": {
    "item_id": "0000000001",
    "data_id": "VTVKMjhqUFdQQkN",
    "item_name": "Keyboard",
    "item_rate": 10000,
    "item_category": "Electronics",
    "item_description": "(description).",
    "submerchant_name": "Qwerty Tech",
    "status": "Active"
  },
  "message": "Details fetched successfully.",
  "status": "success",
  "code": "00"
}

List Items

Retrieve a paginated list of all invoice items.

Endpoint

Method	URL
GET	`https://api.payorc.com/invoice/v1/items/list`

Please use the test credentials for sandbox testing.

Query Parameters

Parameter	Type	Required	Description
`perpage`	Integer	Yes	Number of records per page (1–1000)
`page`	Integer	Yes	Page number (1–1000)
`status`	String	No	Filter by status (`Active` or `Deactivated`)

Code Examples

curl -X GET "https://api.payorc.com/invoice/v1/items/list?perpage=10&page=1" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET"

Example Response

{
  "data": [
    {
      "item_id": "0000000001",
      "data_id": "VTVKMjhqUFdQQkN",
      "item_rate": 10000,
      "item_name": "Keyboard",
      "item_category": "Electronics",
      "item_description": "(description).",
      "submerchant_name": "Qwerty Tech",
      "status": "Active",
      "item_no": "00000001",
      "created_date": "2024-01-20 10:30:00",
      "last_modified_date": "2024-01-20 10:30:00"
    }
  ],
  "message": "List fetched successfully.",
  "status": "success",
  "code": "00",
  "total_records": 1
}

Use the data_id token returned from list operations when adding items to invoices via the invoice API (in the item_data[].data_id field).

Invoice Items

On this page