Products

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.

Properties

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

Retrieve all products

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

Parameters

Attribute	Description
page number optional	Page number to start from. Page numbering starts at 1, and omitting the `page` parameter will return the first page. e.g. `?page=2`
per_page number optional	Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100. e.g. `?per_page=20`
sort_by string optional	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 e.g. `?sort_by=created_at`
ids string optional	Comma-separated list of product IDs to be returned in a request. e.g. `?ids=1,2,3`
name string optional	Name of the product. e.g. `?name=Enterprise%20Plan`
sku string optional	SKU of the product. e.g. `?sku=enterprise-plan`
active boolean optional	Indicator of whether or not the product is active. e.g. `?active=true`

Action

GET /v2/products

Examples

Retrieve all products

GET /v2/products HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/products", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/products',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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

Create a new product.

Products can be created only by an account administrator.

Parameters

Attribute	Description
name string required	e.g. `"name": "Enterprise Plan"`
sku string optional	e.g. `"sku": "enterprise-plan"`
active boolean optional	e.g. `"active": "true"`
cost number optional	e.g. `"cost": "1000"`
cost_currency string optional	e.g. `"cost_currency": "EUR"`
prices array required	e.g. `"prices": [{"amount": "1599.99", "currency": "USD"}, {"amount": "3599.99", "currency": "PLN"}]`

Action

POST /v2/products

Examples

Simple create

POST /v2/products HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "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"
  }
}

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"
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
"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"
}
}
'
response = RestClient.execute method: :post, url: "https://api.getbase.com/v2/products", payload: body, headers: headers

puts response

import requests
import json

payload = {
  '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'
  }
}

response = requests.post(
    url='https://api.getbase.com/v2/products',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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

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

Attribute	Description
id number required	Unique identifier of the product.

Action

GET /v2/products/:id

Examples

Retrieve a product with id 1

GET /v2/products/1 HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/products/1", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/products/1',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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

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

Attribute	Description
id required	Unique identifier of the product.
name string optional	Name of the product. e.g. `"name": "Enterprise Plan"`
description string optional	Description of the product. e.g. `"description": "All-in-one sales platform for data driven enterprises"`
sku string optional	Stock Keeping Unit identification code. e.g. `"sku": "enterprise-plan"`
active boolean optional	Indicator of whether or not the product can be used in new line items. e.g. `"active": "true"`
max_discount number optional	Maximum discount that can be applied to the product in percents. e.g. `"max_discount": "10"`
max_markup number optional	Maximum markup that can be applied to the product in percents. e.g. `"max_markup": "10"`
cost decimal optional	Cost of the product. e.g. `"cost": "10"`
cost_currency string optional	Currency of the product cost, specified in 3-character currency code (ISO4217) format. e.g. `"cost_currency": "EUR"`
prices array optional	Array specifying products prices in different currencies. e.g. `"prices": [{"currency": "USD", "amount": "1599.99"}, {"currency": "PLN", "amount": "3599.99"}]`

Action

PUT /v2/products/:id

Examples

Update a product with id 1

PUT /v2/products/1 HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "active": false
  }
}

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
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
  "data": {
    "active": false
  }
}

'
response = RestClient.execute method: :put, url: "https://api.getbase.com/v2/products/1", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'active': false
  }
}

response = requests.put(
    url='https://api.getbase.com/v2/products/1',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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 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.

Parameters

Attribute	Description
id number required	Unique identifier of the product.

Action

DELETE /v2/products/:id

Examples

Delete a product with id 1

DELETE /v2/products/1 HTTP/1.1

Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
response = RestClient.execute method: :delete, url: "https://api.getbase.com/v2/products/1"

puts response

import requests
import json

response = requests.delete(
    url='https://api.getbase.com/v2/products/1',
    headers={
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 204 No Content

Products

Properties

Endpoints

Retrieve all products

Parameters

Possible values:

Create a product

Parameters

Retrieve a single product

Parameters

Update a product

Parameters

Delete a product

Parameters