Products

cURL Ruby

List all products of an administration

GET /products(.:format)

Returns a paginated list of products in the administration. Each page contains 10 products. You can use the page parameter to fetch the next page of products.

Parameters

Parameter Type Description
query String

Allows filtering by product name.
page Integer

The page to fetch, starting at 1.
currency String

ISO three-character currency code, e.g. EUR or USD.

Example: returns a list of active products

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products.json?

Response

        
          
          Status: 200 OK
        
      
[
  {
    "id": "407012589511378735",
    "administration_id": 123,
    "description": "Apple",
    "title": null,
    "identifier": null,
    "price": "100.0",
    "currency": "EUR",
    "frequency": null,
    "frequency_type": null,
    "tax_rate_id": "407012429954811583",
    "ledger_account_id": "407012429891897003",
    "created_at": "2023-12-12T10:37:54.791Z",
    "updated_at": "2023-12-12T10:37:54.791Z"
  },
  {
    "id": "407012589493552941",
    "administration_id": 123,
    "description": "My product description",
    "title": null,
    "identifier": "SKU1234",
    "price": "100.0",
    "currency": "EUR",
    "frequency": null,
    "frequency_type": null,
    "tax_rate_id": "407012429954811583",
    "ledger_account_id": "407012429891897003",
    "created_at": "2023-12-12T10:37:54.774Z",
    "updated_at": "2023-12-12T10:37:54.774Z"
  },
  {
    "id": "407012589525010225",
    "administration_id": 123,
    "description": "Pie",
    "title": null,
    "identifier": null,
    "price": "100.0",
    "currency": "EUR",
    "frequency": null,
    "frequency_type": null,
    "tax_rate_id": "407012429954811583",
    "ledger_account_id": "407012429891897003",
    "created_at": "2023-12-12T10:37:54.804Z",
    "updated_at": "2023-12-12T10:37:54.804Z"
  }
]

Example: allows filtering by query

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products.json?query=apple

Response

        
          
          Status: 200 OK
        
      
[
  {
    "id": "407012591904229184",
    "administration_id": 123,
    "description": "Apple",
    "title": null,
    "identifier": null,
    "price": "100.0",
    "currency": "EUR",
    "frequency": null,
    "frequency_type": null,
    "tax_rate_id": "407012429954811583",
    "ledger_account_id": "407012429891897003",
    "created_at": "2023-12-12T10:37:57.073Z",
    "updated_at": "2023-12-12T10:37:57.073Z"
  }
]

Example: handles empty search result

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products.json?query=kjashdfjksadhfjk

Response

        
          
          Status: 200 OK
        
      
[

]

Example: returns a paginated response for page 2

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products.json?page=2&per_page=1

Response

        
          
          Status: 200 OK
        
      
[
  {
    "id": "407012594800396128",
    "administration_id": 123,
    "description": "My product description",
    "title": null,
    "identifier": "SKU1234",
    "price": "100.0",
    "currency": "EUR",
    "frequency": null,
    "frequency_type": null,
    "tax_rate_id": "407012429954811583",
    "ledger_account_id": "407012429891897003",
    "created_at": "2023-12-12T10:37:59.835Z",
    "updated_at": "2023-12-12T10:37:59.835Z"
  }
]

Returns information about a product

GET /products/:id(.:format)

Example: returns a single product

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products/407012595066734449.json?

Response

        
          
          Status: 200 OK
        
      
{
  "id": "407012595066734449",
  "administration_id": 123,
  "description": "My product description",
  "title": null,
  "identifier": "SKU1234",
  "price": "100.0",
  "currency": "EUR",
  "frequency": null,
  "frequency_type": null,
  "tax_rate_id": "407012429954811583",
  "ledger_account_id": "407012429891897003",
  "created_at": "2023-12-12T10:38:00.089Z",
  "updated_at": "2023-12-12T10:38:00.089Z"
}

Example: returns 404 when product does not exist

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products/34123123.json?

Response

        
          
          Status: 404 Not Found
        
      
{
  "error": "record not found",
  "symbolic": {
    "id": "not_found"
  }
}

Returns information about a product based on the identifier

GET /products/identifier/:identifier(.:format)

Example: returns a single product based on the identifier

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products/identifier/SKU1234.json?

Response

        
          
          Status: 200 OK
        
      
{
  "id": "407012595239749493",
  "administration_id": 123,
  "description": "My product description",
  "title": null,
  "identifier": "SKU1234",
  "price": "100.0",
  "currency": "EUR",
  "frequency": null,
  "frequency_type": null,
  "tax_rate_id": "407012429954811583",
  "ledger_account_id": "407012429891897003",
  "created_at": "2023-12-12T10:38:00.255Z",
  "updated_at": "2023-12-12T10:38:00.255Z"
}

Example: returns a single product based on the identifier with dot

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products/identifier/aa.bb.json?

Response

        
          
          Status: 200 OK
        
      
{
  "id": "407012595325732727",
  "administration_id": 123,
  "description": "My product description",
  "title": null,
  "identifier": "aa.bb",
  "price": "100.0",
  "currency": "EUR",
  "frequency": null,
  "frequency_type": null,
  "tax_rate_id": "407012429954811583",
  "ledger_account_id": "407012429891897003",
  "created_at": "2023-12-12T10:38:00.337Z",
  "updated_at": "2023-12-12T10:38:00.348Z"
}

Example: returns 404 when product does not exist

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/products/identifier/random.json?

Response

        
          
          Status: 404 Not Found
        
      
{
  "error": "record not found",
  "symbolic": {
    "id": "not_found"
  }
}

Creates a new product

POST /products(.:format)

Parameters

Parameter Type Description
product[title] String
product[description] String
product[price] Decimal

Required

Both a decimal and a string ‘10,95’ are accepted.
product[document_style_id] Integer

Should be a valid document style id.
product[ledger_account_id] Integer

Required

Should be a valid ledger account id.
product[tax_rate_id] Integer

Should be a valid tax rate id.
product[workflow_id] Integer

Should be a valid workflow id.
product[currency] String

Required

ISO three-character currency code, e.g. EUR or USD.
product[checkout_type] String

Can be product or subscription.
product[frequency_type] String

Can be day, week, month, quarter or year.
product[frequency] Integer

Should be an integer >= 1.
product[product_type] String

Can be digital_service, service or product.
product[vat_rate_type] String

Can be standard or reduced.
product[max_amount_per_order] Integer

Should be an integer 0 <= n < 2.
product[identifier] String

Should be unique for the administration.
product[image_hash] String
product[frequency_preset] String

Example: creates a new product

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPOST \
  -d '{"product":{"description":"Geldvogel","price":"50,50","tax_rate_id":407012595537545086,"ledger_account_id":407012595546982272}}' \
  https://moneybird.com/api/v2/123/products.json

Response

        
          
          Status: 201 Created
        
      
{
  "id": "407012595594168194",
  "administration_id": 123,
  "description": "Geldvogel",
  "title": null,
  "identifier": null,
  "price": "50.5",
  "currency": "EUR",
  "frequency": null,
  "frequency_type": null,
  "tax_rate_id": "407012595537545086",
  "ledger_account_id": "407012595546982272",
  "created_at": "2023-12-12T10:38:00.592Z",
  "updated_at": "2023-12-12T10:38:00.592Z"
}

Example: returns an error when information is missing

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPOST \
  -d '{"product":{"title":"","description":"","price":"","tax_rate_id":407012595665471367,"ledger_account_id":407012595674908553}}' \
  https://moneybird.com/api/v2/123/products.json

Response

        
          
          Status: 422 Unprocessable Entity
        
      
{
  "error": {
    "title": [
      "cannot be empty"
    ],
    "description": [
      "cannot be empty"
    ],
    "base": [
      "must contain a title or description"
    ]
  }
}

Updates a product

PATCH /products/:id(.:format)

Parameters

Parameter Type Description
product[title] String
product[description] String
product[price] Decimal

Both a decimal and a string ‘10,95’ are accepted.
product[tax_rate_id] Integer

Should be a valid tax rate id.
product[ledger_account_id] Integer

Should be a valid ledger account id.
product[currency] String

ISO three-character currency code, e.g. EUR or USD.
product[frequency_type] String

Can be day, week, month, quarter or year.
product[frequency] Integer

Should be an integer >= 1.
product[product_type] String

Can be digital_service, service or product.
product[vat_rate_type] String

Can be standard or reduced.
product[checkout_type] String

Can be product or subscription.
product[max_amount_per_order] Integer

Should be an integer 0 <= n < 2.
product[document_style_id] Integer

Should be a valid document style id.
product[workflow_id] Integer

Should be a valid workflow id.
product[identifier] String

Should be unique for the administration.
product[image_hash] String
product[frequency_preset] String

Example: updates a product

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"product":{"description":"Updated","price":"123"}}' \
  https://moneybird.com/api/v2/123/products/407012595771377547.json

Response

        
          
          Status: 200 OK
        
      
{
  "id": "407012595771377547",
  "administration_id": 123,
  "description": "Updated",
  "title": null,
  "identifier": "SKU1234",
  "price": "123.0",
  "currency": "EUR",
  "frequency": null,
  "frequency_type": null,
  "tax_rate_id": "407012429954811583",
  "ledger_account_id": "407012429891897003",
  "created_at": "2023-12-12T10:38:00.761Z",
  "updated_at": "2023-12-12T10:38:00.818Z"
}

Deletes a product

DELETE /products/:id(.:format)

Example: deletes a product

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XDELETE \
  -d '{}' \
  https://moneybird.com/api/v2/123/products/407012595921323918.json

Response

        
          
          Status: 204 No Content

Example: deactivates the product when product has details

Request

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XDELETE \
  -d '{}' \
  https://moneybird.com/api/v2/123/products/407012596045055890.json

Response

        
          
          Status: 204 No Content