Skip to content

Categories

Categories organize the line items used on Flute invoices.

Categories are intended to be a convenient way to group and locate line items. Line items are used to create invoices. Each line item is product or service with predefined values such a name, unit type, and price. To build an invoice, add the appropriate line items to itemize billing.

Categories can organize groups of line items. The use of categories is optional.

A category may contain zero, one or more line items. Line items may be assigned to a category. However, line items are not required to be assigned to a category. For more about line items, see Line Items.

Each category has:

  • A name, which must be unique within a merchant account.
  • An optional default unit type, such as each, hour, or pound, that applies automatically to line items created under it.

A category may be deleted, This does not delete the line items assigned to it. Those line items will remain but without a category.

Each category returned by the API also reports an item count. This gives a quick view of how many line items currently belong to it. With that information, a merchant may decide to rename, reassign, or delete it.

The Categories endpoints support listing, creating, updating, and removing categories. The following endpoints are available:

EndpointExplanation
GET /pay-int-api/categoriesThe list endpoint accepts a search string along with paging and sort parameters. A merchant catalog with many categories can be filtered to relevant results rather than paged through in full.
POST /pay-int-api/categoriesCreates a new category. The category name must be unique within the merchant account.
PUT /pay-int-api/categories/{categoryId}Updates an existing category's name or default unit type. The name must remain unique within the merchant account.
DELETE /pay-int-api/categories/{categoryId}Deletes a category. Line items that referenced it stay in the catalog, now with an empty category.
Operations

Retrieves a list of categories

Request

GET {{baseURL}}/pay-int-api/categories

This endpoint retrieves a paginated list of the merchant's categories.

Results can be narrowed with the search parameter for a case-insensitive, partial-match lookup. This includes by name, and sorted using the orderby and asc parameters.

See Also:
To create a category, see POST /pay-int-api/categories.
To update a category, see PUT /pay-int-api/categories/{categoryId}.
To delete a category, see DELETE /pay-int-api/categories/{categoryId}.

Security
Bearer
Query
searchstring

Specifies the search string.

This performs a case insensitive, matching, or partially matching search.

The name field is searched. If the results are to be sorted, use the field orderby to specify the sort field.

Example: Peppared

Example:search=Peppared
pageinteger, (int32)

Specifies the page number of the returned search results.

A page is considered each set of the pageSize value.

The maximum page value is the pageSize divided by the total count rounded up. The count is zero-based. For example, if pageSize is 50 and the total is 130, there are three pages. The maximum page value is 2.

Values above the maximum page value will complete successfully but not return any items.

Example: 0

Default:0
pageSizeinteger, (int32)

Specifies the number of items for each page of the returned search results.

A page is considered each set of the pageSize value.

The maximum page value is the pageSize divided by the total count rounded up. The count is zero-based. For example, if pageSize is 50 and the total is 130, there are three pages. The maximum page value is 2.

Example: 50

Default:15
orderBystring

Specifies the field the results get ordered by.

The sort order is specified by the asc value.

Example: contactName

ascboolean

Specifies the sort order.

The sort field is specified by the orderBy value.

If true, the sort order is ascending.
If false, the sort order is descending.

Example: false

Default:false
Headers
x-api-versionstring

Specifies the API version to use for the request.

Example: 1.0

Example:1.0
curl -i -X GET \
  'https://developer.flute.com/_mock/api-reference/pay-int-api/categories?search=Peppared&page=0&pageSize=15&orderBy=string&asc=false' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'x-api-version: 1.0'

Responses

OK

Bodyapplication/json
itemsArray of objects or null

Categories for the current page.

totalinteger, (int32)

Indicates the total number of categories found.

Example: 7

Example:7
Response
{
  "items": [
    {
      "name": "After-market sales",
      "id": "567ef5a6-7b8c-4d9e-0f1a-2b3c4d5e6f92",
      "defaultUnitTypeId": 32,
      "itemCount": 8
    }
  ],
  "total": 7
}