Response structure

All API responses follow a consistent and predictable structure. This helps you parse data and implement integrations. The structure supports both single resources and lists of resources.

Top-level structure

Every API response includes a top-level data field. The type of content in data depends on the request:

• For a single resource, data is an object.
• For a list of resources, data is an array of objects.

List responses may also include links and meta objects to support pagination.

Example (single resource)

{
  "data": { ... }
}

Example (list response)

{
  "data": [ ... ],
  "links": { ... },
  "meta": { ... }
}

Field naming conventions

Field names use snake_case. This naming pattern applies to the following:

• Identifiers: id, company_id, product_id
• Timestamps: created_at, updated_at
• Boolean flags: published, unrestricted, allow_add_to_cart

Resource IDs

Each resource includes a unique top-level id. If a resource is related to other entities, it also includes foreign key references, such as the following:

• company_id
• map_promotion_id
• product_id

These IDs make it easier to join or filter related data.

Nested objects

Some fields include nested objects that group related information. For example:

"map_advertising_pricing": {
  "code": "MAP_MINIMUM",
  "description": "MAP is Minimum Price"
}

Other examples include nested company, retailer, and inventories objects.

Nullable fields

When a value isn’t available, the field is still included and set to null. This makes the schema predictable and reduces the need for null-checking.

Pagination

For responses that return multiple records, the API includes pagination information in links and meta. For details, go to Pagination.

Optional message and status metadata

Some responses include a message field for human-readable feedback:

{
  "data": { ... },
  "message": "Product inventories updated successfully."
}

In batch operations, the data object might include fields like skipped_records to indicate partial success.

Table of common fields

The following table lists the common fields of BFG API responses: