BrightCom API Reference on BrightCom Docs

Item

Mon, 01 Jan 0001 00:00:00 +0000

An item message can represent one of three conceptual shapes:

Non-Variant Item — has no variations, sold as-is.
Item with Variants — has variants in BC, sold at the variant level. Populate variants.
Item with Parent — structurally an item in BC (like a non-variant item), but has a virtual parent that doesn’t exist as an item in BC. Used to let external systems group these as if they were variants of a common parent. Populate parentPartNo.

Not a field you set

This classification is conceptual, not a literal field on the wire — there’s a class property internally, but it’s excluded from JSON entirely (confirmed via the shipped model: it carries a [JsonIgnore] attribute). Which shape you’re sending is determined by which of the fields above you populate, not by declaring a type.

Queue semantics

If an item with the same identifier already exists in the queue, the new entry is added at the back as a copy, not merged in place. If the queue holds two or more copies of the same identifier with byte-wise identical content, they’re deduplicated on retrieval; copies that differ are delivered in FIFO order. Posted items are filtered and transformed against the configured targets before delivery — an item can be culled entirely if it doesn’t match a target’s filters.

Customer

Mon, 01 Jan 0001 00:00:00 +0000

Creates or updates customers in Business Central. If a customer already exists on the queue, the entry is replaced by the new one — matched by e-mail address if present, otherwise by customer code.

Add customers to the queue

POST https://onbrightcom.com/gateway/v1/customer

Accepts a JSON array of customer entries.

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`customerNumber`	string
`source`	string
`firstName`	string
`lastName`	string
`companyName`	string
`customerType`	string
`email`	string	Used as the upsert key if present
`phone`	string
`mobilePhone`	string
`vatNumber`	string
`orgNumber`	string
`currency`	string
`warehouseId`	string
`invoiceToCountryCode`	string
`shipToCountryCode`	string
`invoicingAddress`	object	See Address below
`shipToAddress`	object	See Address below
`shipToAddresses`	array of object	Multiple named delivery addresses, each shaped like Address
`extendedInfo`	array	See Extended Info
`checksum`	string
`hasVatNumber`	boolean
`hasCustomerNumber`	boolean
`contacts`	array of object	See Contact below

Request

[
 {
 "externalId": "20000",
 "customerNumber": "20000",
 "source": "example-shop",
 "firstName": "Anna",
 "lastName": "Karlsson",
 "customerType": "Person",
 "email": "anna.karlsson@example.com",
 "phone": "+46 31 555 0123",
 "currency": "SEK",
 "invoicingAddress": {
 "address1": "Storgatan 4",
 "city": "Göteborg",
 "zip": "411 03",
 "country": "SE"
 },
 "extendedInfo": []
 }
]

Response

201 Created
"1 customer(s) queued"

Address

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`defaultAddress`	boolean
`code`	string
`contact`	string
`address1`	string
`address2`	string
`zip`	string
`city`	string
`county`	string
`country`	string
`phone`	string
`extendedInfo`	array	See Extended Info
`checksum`	string

Contact

Field	Type	Notes
`code`	string
`firstName`	string
`lastName`	string
`email`	string
`phone`	string
`mobilePhone`	string
`jobTitle`	string
`extendedInfo`	array	See Extended Info — Customer is one of the resources where Extended Info appears at more than one level: on the customer itself, and independently on each contact.

Retrieve customers from the queue

GET https://onbrightcom.com/gateway/v1/customer

Query parameter	Notes
`count`	Number of entries to retrieve. Default 100 if omitted.
`acknowledge`	The `acknowledgeToken` from your previous batch — pass it to close that batch and advance the queue.

{
 "count": 1,
 "acknowledgeToken": "5b2f7c1a-8d4e-4b9a-9f31-2c6a8e1d4b90",
 "nextLink": "/customer?acknowledge=5b2f7c1a-8d4e-4b9a-9f31-2c6a8e1d4b90",
 "data": [
 {
 "externalId": "20000",
 "customerNumber": "20000",
 "firstName": "Anna",
 "lastName": "Karlsson",
 "email": "anna.karlsson@example.com",
 "extendedInfo": []
 }
 ]
}

Price

Mon, 01 Jan 0001 00:00:00 +0000

Each entry targets an item (optionally a specific variant) on a given price list, with price, VAT, and currency.

Add price entries to the queue

POST https://onbrightcom.com/gateway/v1/price

Accepts a JSON array of price entries.

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`partNo`	string
`source`	string
`variantCode`	string
`priceListCode`	string
`priceListName`	string
`appliesToType`	string
`appliesToCode`	string
`campaign`	boolean	Flags this entry as campaign pricing — not a campaign code/name
`price`	number
`vat`	number
`previousPrice`	number
`previousVat`	number
`currencyCode`	string
`validFrom`	datetime
`validUntil`	datetime
`created`	datetime
`checksum`	string
`extendedInfo`	array	See Extended Info
`minimumQuantity`	number
`unitOfMeasure`	string
`productRanges`	array	Channel/assortment flags — see Extended Info for how this differs from `extendedInfo`

Request

[
 {
 "externalId": "10023-050-ONE-SUMMER26",
 "partNo": "10023",
 "source": "example-pim",
 "variantCode": "050-ONE",
 "priceListCode": "SUMMER26",
 "priceListName": "Summer Campaign 2026",
 "appliesToType": "Item",
 "appliesToCode": "10023",
 "campaign": true,
 "price": 249.00,
 "vat": 25,
 "currencyCode": "SEK",
 "validFrom": "2026-06-01T00:00:00Z",
 "validUntil": "2026-08-31T23:59:59Z",
 "unitOfMeasure": "PCS",
 "extendedInfo": []
 }
]

Response

201 Created
"1 price(s) queued"

Retrieve price entries from the queue

GET https://onbrightcom.com/gateway/v1/price

Query parameter	Notes
`count`	Number of entries to retrieve. The API docs describe a default of 100 if omitted, though unlike the other resources this parameter has no code-level default value — pass it explicitly to be safe.
`acknowledge`	The `acknowledgeToken` from your previous batch — pass it to close that batch and advance the queue.

{
 "count": 1,
 "acknowledgeToken": "3b6a1f0e-9c2d-4e11-8a77-1e2f9b6d4c10",
 "nextLink": "/price?acknowledge=3b6a1f0e-9c2d-4e11-8a77-1e2f9b6d4c10",
 "data": [
 {
 "externalId": "10023-050-ONE-SUMMER26",
 "partNo": "10023",
 "variantCode": "050-ONE",
 "priceListCode": "SUMMER26",
 "price": 249.00,
 "currencyCode": "SEK",
 "extendedInfo": []
 }
 ]
}

Warehouse

Mon, 01 Jan 0001 00:00:00 +0000

Inventory levels and stock movements per warehouse, item, and variant — as absolute quantities and/or delta adjustments, optionally with incoming quantity, next delivery date, and forward planning / historical consumption data.

Add warehouse entries to the queue

POST https://onbrightcom.com/gateway/v1/warehouse

Accepts a JSON array of warehouse entries.

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`checksum`	string
`warehouseExternalId`	string
`sourceWarehouseExternalId`	string	For transfer-type movements
`destinationWarehouseExternalId`	string	For transfer-type movements
`messageType`	string
`comment`	string
`source`	string
`partNo`	string
`variantCode`	string
`quantity`	number	Absolute quantity
`deltaQuantity`	number	Adjustment relative to the last known quantity
`created`	datetime
`incomingQuantity`	number
`nextDelivery`	datetime
`reasonCode`	string
`transactionId`	string
`name`	string
`extendedInfo`	array	See Extended Info
`type`	string
`period`	string
`planning`	array of object	See Planning below
`history`	array of object	See History below
`productRanges`	array	Channel/assortment flags

Request

[
 {
 "externalId": "MAIN-10023-050-ONE",
 "warehouseExternalId": "MAIN",
 "source": "example-erp",
 "partNo": "10023",
 "variantCode": "050-ONE",
 "quantity": 42,
 "deltaQuantity": -3,
 "created": "2026-08-26T08:00:00Z",
 "incomingQuantity": 100,
 "nextDelivery": "2026-09-05T00:00:00Z",
 "extendedInfo": []
 }
]

Response

201 Created
"1 warehouse entr(y/ies) queued"

Planning

Field	Type
`startPeriod`	datetime
`endPeriod`	datetime
`quantityPhysical`	number
`scheduledReceipt`	number
`grossRequirement`	number
`quantity`	number

History

Field	Type
`periodStart`	datetime
`periodEnd`	datetime
`periodStartInventory`	number
`purchases`	number
`sales`	number
`other`	number
`periodEndInventory`	number

Retrieve warehouse entries from the queue

GET https://onbrightcom.com/gateway/v1/warehouse

Query parameter	Notes
`count`	Number of entries to retrieve. Default 100 if omitted.
`acknowledge`	The `acknowledgeToken` from your previous batch — pass it to close that batch and advance the queue.

{
 "count": 1,
 "acknowledgeToken": "6c2e9a4d-1a3b-4f60-9e0c-2d7a5f8b3c11",
 "nextLink": "/warehouse?acknowledge=6c2e9a4d-1a3b-4f60-9e0c-2d7a5f8b3c11",
 "data": [
 {
 "externalId": "MAIN-10023-050-ONE",
 "warehouseExternalId": "MAIN",
 "partNo": "10023",
 "variantCode": "050-ONE",
 "quantity": 42,
 "extendedInfo": []
 }
 ]
}

Order

Mon, 01 Jan 0001 00:00:00 +0000

An order message serves three purposes, distinguished by documentType:

order (default) — a sales order. Normally generates a sales order in the ERP; also used by the ERP to send order status back to the source system.
invoice — an order that’s already closed and shipped, such as a receipt from a point-of-sale system.
credit memo — a credit memo that’s already closed.

Required fields for a successful order

source (origin — use your tenant code unless told otherwise), orderDate, externalId, primaryWarehouseId (optional), buyer (with at least an invoicing address including a country code), shipTo (optional; set shipToAddresses to one element on it), payments (at least a code and amount, multiple allowed), currency (optional), totalAmount, totalExclVat, totalVat, totalFreight (required if there’s no line for shipping), totalFreightVat.

Shipment

Mon, 01 Jan 0001 00:00:00 +0000

Reports a fully or partially shipped order.

Add a shipment to the queue

POST https://onbrightcom.com/gateway/v1/shipment

Accepts either a single shipment object or a JSON array — the request body is sniffed for a leading [. An explicit batch route also exists at POST /shipment/shipments (identical List body) if you’d rather always send arrays.

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`source`	string
`created`	datetime
`closed`	datetime
`expectedDeliveryDate`	datetime
`sourceWarehouseId`	string
`targetWarehouseId`	string
`status`	string
`completelyShipped`	boolean
`completleyReceived`	boolean	Spelled exactly like this on the wire (“Completley”) — a typo in the underlying model, not yours to fix
`lines`	array of object	See Shipment line below
`extendedInfo`	array	See Extended Info
`checksum`	string
`sourceName`	string
`targetName`	string
`reasonCode`	string
`documentType`	string
`trackingUrl`	string
`trackingNo`	string

Request

{
 "externalId": "SHP-088310",
 "source": "example-erp",
 "created": "2026-08-26T08:47:12Z",
 "sourceWarehouseId": "MAIN",
 "completelyShipped": true,
 "trackingNo": "1234567890",
 "lines": [
 {
 "partNo": "10023",
 "variantCode": "050-ONE",
 "name": "Outdoor Scarf",
 "quantity": 1,
 "handledQuantity": 1,
 "closedQuantity": 1
 }
 ],
 "extendedInfo": []
}

Response

201 Created
"1 shipment(s) queued"

Shipment line

Field	Type	Notes
`id`	string (GUID)
`externalId`	string
`partNo`	string
`variantCode`	string
`name`	string
`quantity`	number
`handledQuantity`	number
`closedQuantity`	number
`extendedInfo`	array	See Extended Info — Shipment is one of the resources where it appears at both header and line level
`status`	string
`checksum`	string
`price`	number
`cost`	number
`reasonCode`	string

Retrieve shipments from the queue

GET https://onbrightcom.com/gateway/v1/shipment

Query parameter	Notes
`count`	Number of entries to retrieve. Default 100 if omitted.
`acknowledge`	The `acknowledgeToken` from your previous batch — pass it to close that batch and advance the queue.

{
 "count": 1,
 "acknowledgeToken": "1a4c8e6f-2b9d-4e33-a0f1-7c5d9e2b4a88",
 "nextLink": "/shipment?acknowledge=1a4c8e6f-2b9d-4e33-a0f1-7c5d9e2b4a88",
 "data": [
 {
 "externalId": "SHP-088310",
 "sourceWarehouseId": "MAIN",
 "completelyShipped": true,
 "trackingNo": "1234567890",
 "extendedInfo": []
 }
 ]
}

A GET /shipment/shipments also exists — don't use it

There’s also a GET /shipment/shipments route that just redirects to the same result as GET /shipment above. It’s hidden from the published API spec and marked in the Gateway’s own source as unexplained leftover (“Todo: why do we have this redirect?”). Use GET /shipment.

Extended Info

Mon, 01 Jan 0001 00:00:00 +0000

From the Gateway’s own documentation: “All messages can be extended beyond their base models, using our Extended Info format.” It’s a first-party, cross-cutting mechanism — not specific to one resource — used to carry source-specific attributes (HS codes, season identifiers, supplier information, and similar) that don’t have a dedicated field on the base message.

It’s flexible in two ways: the set of codes is configurable, not fixed, and it can appear at more than one level on a message — e.g. independently on an item and on each of its variants, or on an order and on each of its lines.