Products

A product describes what you sell (goods or services). A product determines how what you sell appears on invoices and receipts. The pricing for products is set in Plans. One product can have many plans.

Retrieve a list of products

Retrieve a list of products.

Authorizations:
query Parameters
filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array ()
id
string <= 50 characters

The product ID.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

The product created time.

updatedTime
string <date-time>

The product updated time.

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

// all parameters are optional
const firstCollection = await api.products.getAll();

// alternatively you can specify one or more of them
const params = {limit: 20, offset: 100, sort: '-createdTime'}; 
const secondCollection = await api.products.getAll(params);

// access the collection items, each item is a Member
secondCollection.items.forEach(product => console.log(product.fields.name));

Response samples

Content type
application/json
[
  • {
    }
]

Create a Product

Create a Product.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Product resource.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
id
string <= 50 characters

The product ID.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

The product created time.

updatedTime
string <date-time>

The product updated time.

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "name": "Premium membership",
  • "unitLabel": "seat",
  • "description": "string",
  • "requiresShipping": false,
  • "options": [
    ],
  • "customFields": {
    },
  • "taxCategoryId": "00000",
  • "accountingCode": "4010"
}

Response samples

Content type
application/json
{
  • "id": "membership",
  • "name": "Premium membership",
  • "unitLabel": "seat",
  • "description": "string",
  • "requiresShipping": false,
  • "options": [
    ],
  • "customFields": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "taxCategoryId": "00000",
  • "accountingCode": "4010",
  • "_links": [
    ]
}

Retrieve a product

Retrieve a product with specified identifier string.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
id
string <= 50 characters

The product ID.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

The product created time.

updatedTime
string <date-time>

The product updated time.

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

const product = await api.products.get({id: 'foobar-001'});
console.log(product.fields.name);

Response samples

Content type
application/json
{
  • "id": "membership",
  • "name": "Premium membership",
  • "unitLabel": "seat",
  • "description": "string",
  • "requiresShipping": false,
  • "options": [
    ],
  • "customFields": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "taxCategoryId": "00000",
  • "accountingCode": "4010",
  • "_links": [
    ]
}

Upsert a product with predefined ID

Create or update a product with predefined identifier string.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

Product resource.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
id
string <= 50 characters

The product ID.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

The product created time.

updatedTime
string <date-time>

The product updated time.

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Array of objects (SelfLink) non-empty

The links related to resource.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
id
string <= 50 characters

The product ID.

name
required
string <= 255 characters

The product name.

unitLabel
string <= 50 characters
Default: "unit"

The unit label, such as per seat or per unit.

description
string <= 512 characters

The product description.

requiresShipping
boolean

If the product requires shipping, shipping calculations will be applied.

options
Array of strings

The product options such as color, size, etc. The product options definition does not include option values. Those are defined within the plans.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

createdTime
string <date-time>

The product created time.

updatedTime
string <date-time>

The product updated time.

taxCategoryId
string
Enum: "00000" "99999" "20010" "40030" "51020" "51010" "31000" "30070"

The product's tax category identifier string.

accountingCode
string

The product accounting code.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "name": "Premium membership",
  • "unitLabel": "seat",
  • "description": "string",
  • "requiresShipping": false,
  • "options": [
    ],
  • "customFields": {
    },
  • "taxCategoryId": "00000",
  • "accountingCode": "4010"
}

Response samples

Content type
application/json
{
  • "id": "membership",
  • "name": "Premium membership",
  • "unitLabel": "seat",
  • "description": "string",
  • "requiresShipping": false,
  • "options": [
    ],
  • "customFields": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "taxCategoryId": "00000",
  • "accountingCode": "4010",
  • "_links": [
    ]
}

Delete a product

Delete a product with predefined identifier string.

Authorizations:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Request samples

const request = await api.products.delete({id: 'my-second-key'});

// the request does not return any fields but
// you can confirm the success using the status code
console.log(request.response.status); // 204

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}