The Products API provides a simple interface to manage the Product Catalog.

The catalog lists products available in your account. To add products to a deal, you should create an Order, then populate it with Line Items.

The API allows you to create, delete and update your products. You can also retrieve a single product as well as list of all products.

All users can read the Product Catalog, but it can be edited only by an account administrator. However, changes to products can be completely disabled in account's settings. When disabled, all data are preserved and only GET requests are allowed, even for administrators.

Line Items, Products and Orders are available only to users who are on the Enterprise plan.

JSON format

Name Read Only Type Description
id true number Unique identifier of the product.
name true string Name of the product.
description false string Description of the product.
sku false string Stock Keeping Unit identification code.
active false boolean Indicator of whether the product is active. Line items cannot be created from inactive products.
max_discount false number Maximum discount that can be applied to the product in percents.
max_markup false number Maximum markup that can be applied to the product in percents.
cost false decimal Cost of the product. Visible only to account administrators.
cost_currency false string Currency of the product cost, specified in 3-character currency code (ISO4217) format. Visible only to account administrators.
prices true array Array specifying products prices in different currencies.
created_at true string Date and time that the product was created in UTC (ISO8601 format).
updated_at true string Date and time of the last update on the product in UTC (ISO8601 format).

Retrieve all products

GET /v2/products

Returns all products from the catalog according to the parameters provided.

Parameters

Name Required Type In Description
page optional number Query Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_page false number Query Number of records to return per page. Maximum is 500. Defaults to 25.
sort_by false string Query A field to sort by. Default ordering is ascending. If you want to change the sort ordering to descending, append :desc to the field e.g. sort_by=value:desc. Possible values: id, updated_at, created_at
ids false string Query Comma-separated list of product IDs to be returned in a request.
name false string Query Name of the product.
sku false string Query SKU of the product.
active false boolean Query Indicator of whether or not the product is active.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/products \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 1,        "name": "Enterprise Plan",        "sku": "enterprise-plan",        "description": "Includes more storage options",        "active": true,        "prices": [          {            "amount": "1599.99",            "currency": "USD"          },          {            "amount": "3599.99",            "currency": "PLN"          }        ],        "cost": "999.99",        "cost_currency": "USD",        "max_discount": 15,        "max_markup": null,        "created_at": "2014-08-27T16:32:56Z",        "updated_at": "2014-08-27T17:32:56Z"      },      "meta": {        "type": "product"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/products?page=1&per_page=25"    }  }}

Create a product

POST /v2/products

Create a new product.

Products can be created only by an account administrator.

Parameters

Name Required Type In Description
name true string Body e.g. Enterprise Plan
sku false string Body e.g. enterprise-plan
description false string Body Description of the product.
active false boolean Body Whether the product is active. Defaults to true.
cost false number Body e.g. 1000
cost_currency false string Body e.g. EUR
max_discount false number Body Maximum discount on product. Accepts 0-100 (inclusive). Defaults to 0.
max_markup false number Body Maximum markup on product. Minimum is 0. Defaults to 0.
prices true array Body e.g. [{"amount": "1599.99", "currency": "USD"}, {"amount": "3599.99", "currency": "PLN"}]

Allowed for

  • Admins

Using cURL

curl -v -X POST https://api.getbase.com/v2/products \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "active": true,    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "cost": "1599.99",    "cost_currency": "USD",    "max_discount": 15  },  "meta": {    "type": "product"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": true,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Retrieve a single product

GET /v2/products/:id

Returns a single product, according to the unique product ID provided. If the specified product does not exist, the request will return an error.

Parameters

Name Required Type In Description
id true number Query Unique identifier for the product.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/products/1 \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": true,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Update a product

PUT /v2/products/:id

Updates product information. If the specified product does not exist, the request will return an error.

Products can be modified only by an account administrator.

In order to modify prices used on a record, you need to supply the entire set. prices are replaced every time they are used in a request.

Parameters

Name Required Type In Description
id true number Query Unique identifier for the product.
name false string Body Name of the product.
description false string Body Description of the product.
sku false string Body Stock Keeping Unit identification code.
active false boolean Body Indicator of whether or not the product can be used in new line items.
max_discount false number Body Maximum discount that can be applied to the product in percents.
max_markup false number Body Maximum markup that can be applied to the product in percents.
cost false decimal Body Cost of the product.
cost_currency false string Body Currency of the product cost, specified in 3-character currency code (ISO4217) format.
prices false array Body Array specifying products prices in different currencies. e.g. [{"currency": "USD", "amount": "1599.99"}, {"currency": "PLN", "amount": "3599.99"}]

Allowed for

  • Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/products/1 \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "active": false  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": false,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Delete a product

DELETE /v2/products/:id

Delete an existing product from the catalog. Existing orders and line items are not affected. If the specified product does not exist, the request will return an error. This operation cannot be undone.

Products can be removed only by an account administrator.

Name Required Type In Description
id true number Query Unique identifier for the product.

Allowed for

  • Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/products/1 \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content