Create a product

Add something to your catalog from your own system rather than by hand.

post /api/public/v1/products

Headers

Header	Value	Why
X-AUTH-TOKEN	obl_live_...	Your API key. Every call needs one.
Content-Type	application/json	This call sends a body.
Idempotency-Key	a value unique to this request	So a retry whose first answer got lost cannot create a second record.

What you send

Every field here is one you can set. The rest are ours to fill in.

Request body fields
Field	Type
name	string
description	string
productNumber	string
articleCode	string
ean	string
upcCode	string
hsnCode	string
brand	string
model	string
type	string
version	string
remark	string
infoUrl	string
serialNumber	string
labels	string
tags	array
categoryId	string
unitId	string
status	string
isInactive	boolean
isSaleItem	boolean
isPurchaseItem	boolean
isStockItem	boolean
isCatalogItem	boolean
isWebShop	boolean
isFeaturedProduct	boolean
stockProductType	string
validFrom	string
validTo	string
salePrice	string money
saleRrpPrice	string money
salePriceIncludesTax	boolean
salePriceDecimals	integer
saleTaxCode	string
saleTaxStatus	string
isSaleIndividual	boolean
isShippingRequired	boolean
isShippingTaxable	boolean
saleLedgerAccountCode	string
purchaseLedgerAccountCode	string
stockLedgerAccountCode	string
cogsLedgerAccountCode	string
stockQuantity	number
stockMinimalQuantity	number
stockLocation	string
quantityDefault	number
quantityBackorder	number
stockDescription	string
stockDocumentTypes	array
color	string
diameter	string
depth	string
height	string
length	string
opening	string
width	string
volume	string
weight	string

Fields marked money come back as decimal strings like "1234.5600". Keep the string, or hand it to something that does decimal arithmetic.

The call

Request

curl -X POST https://app.obraledger.com/api/public/v1/products \
  -H "X-AUTH-TOKEN: obl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'

Want to fill this in and run it? Open it in the playground.

What comes back

One product.

Shape of the response

Generated from the contract, so it is every field and nothing invented. The values are type names rather than a specimen record - we won't put made-up data on a page.

{
  "id": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "name": "string",
  "description": "string",
  "productNumber": "string",
  "articleCode": "string",
  "ean": "string",
  "upcCode": "string",
  "hsnCode": "string",
  "brand": "string",
  "model": "string",
  "type": "string",
  "version": "string",
  "remark": "string",
  "infoUrl": "string",
  "serialNumber": "string",
  "labels": "string",
  "tags": [],
  "categoryId": "string",
  "unitId": "string",
  "status": "string",
  "isInactive": false,
  "isSaleItem": false,
  "isPurchaseItem": false,
  "isStockItem": false,
  "isCatalogItem": false,
  "isWebShop": false,
  "isFeaturedProduct": false,
  "stockProductType": "string",
  "validFrom": "string",
  "validTo": "string",
  "salePrice": "decimal string",
  "saleRrpPrice": "decimal string",
  "salePriceIncludesTax": false,
  "salePriceDecimals": 0,
  "saleTaxCode": "string",
  "saleTaxStatus": "string",
  "isSaleIndividual": false,
  "isShippingRequired": false,
  "isShippingTaxable": false,
  "saleLedgerAccountCode": "string",
  "purchaseLedgerAccountCode": "string",
  "stockLedgerAccountCode": "string",
  "cogsLedgerAccountCode": "string",
  "stockQuantity": 0,
  "stockMinimalQuantity": 0,
  "stockLocation": "string",
  "quantityDefault": 0,
  "quantityBackorder": 0,
  "stockDescription": "string",
  "stockDocumentTypes": [],
  "color": "string",
  "diameter": "string",
  "depth": "string",
  "height": "string",
  "length": "string",
  "opening": "string",
  "width": "string",
  "volume": "string",
  "weight": "string"
}

When it fails

Match on the type in the body, not on the status. A 403 covers both "this key can't do that" and "this record won't allow it", and the number alone can't tell you which.

400 The request could not be read as a request.

malformed_request
401 Authentication failed — the `X-AUTH-TOKEN` header is missing, malformed, revoked, or belongs to a different company. Not retryable: the same token will fail identically.

unauthenticated
403 Authenticated, but not allowed to do this.

forbidden scope_required
422 The request was understood and its content was rejected.

validation_failed idempotency_key_required
429 Rate limit exceeded for this API key. `Retry-After` says how many seconds to wait; `X-RateLimit-Limit` and `X-RateLimit-Remaining` report the budget on every response, not just this one.

rate_limited

The rest of products

Base URL https://app.obraledger.com. This page is generated from the contract the product publishes.

Building something and stuck? Tell us - we'd rather hear it than have you guess.