Skip to main content
Added v2 endpoints for Attributes, Customers (including addresses and contacts), Orders, Products, and Invoices.

​
What changed per resource

​
New EndpointBreaking
Route: /v2/attributes
New data_type values for product-scoped attributes
  • single_select_swatch — single-select, shown as image swatches on the storefront.
  • multi_select_swatch — multi-select, shown as image swatches.
  • color — single-select backed by a hex colour code, shown as a colour swatch.
New request fields — configuration.options[]
  • image_url — image for this option, used by the swatch data types.
  • color_code — hex colour such as #FF5733, used by the color data type.
Changed response — options[]Each option is now an object with label, value, image_url, and color_code instead of a plain string, on list, create, and update.
​
New EndpointBreaking
Route: /v2/customers
New query parameters — list
  • ids — filter by customer UUID. Repeatable: ?ids=<uuid>&ids=<uuid>.
  • source — return only customers from these sources, such as openapi or sales_rep. Repeatable.
  • exclude_source — the inverse. Repeatable.
New request fields — create & update
  • tax_rate — customer-level tax rate applied at order time. Send 0 to clear it.
  • customer_type — free-text classification such as retail or wholesale.
New on update only
  • status — active or inactive. v1 could not change status through PATCH.
Changed request behaviour — update
  • primary_contact_id, default_shipping_address_id, default_billing_address_id — removed. Use the nested addresses and contacts objects instead.
  • Nested addresses[].id and contacts[].id are now optional. Omit id to create inline, include it to update. v1 required id, so creating meant a second call.
New response fields
  • tax_rate, customer_type, and source on list, create, detail, and update.
Changed response — nested addresses and contacts
  • Addresses gain state_info and country_info (each with code, short_code, name).
  • Addresses no longer return customer_id or status; contacts no longer return status.
​
New EndpointBreaking
Routes: /v2/customers/addresses, /v2/customers/contacts
Route mappingContacts follow the same pattern under /v2/customers/contacts and /v2/customers/{customer_id}/contacts.What changed
  • List is no longer scoped to one customer. customer_id moves from the path to an optional query parameter, so you can page through every address or contact in the account, or filter with ?customer_id=<uuid>.
  • Get by ID no longer needs customer_id in the path.
  • Update is PATCH. Same body as v1, but send only the fields you are changing.
  • Create and delete keep the nested route.
New query parameters — list
  • customer_id — optional filter that replaces the old path segment.
  • reference_ids — filter by your own external IDs. Repeatable.
New response fields
  • state_info and country_info (code, short_code, name) on addresses.
  • customer_id, since the route no longer carries it.
Removed response fields
  • status on both addresses and contacts.
​
New Endpoint
Route: /v2/orders
New and changed query parameters — list
  • ids, customer_ids, customer_reference_ids — filter by order UUID, customer UUID, or your own customer IDs. All repeatable.
  • type — return only order or only quote records.
  • exclude_source — omit orders from these sources. Repeatable.
  • order_status — now also accepts submitted, alongside draft, confirmed, and cancelled. Still defaults to confirmed.
  • source — now repeatable; v1 took a single value.
New request fields — create & update
  • payment_method — set the payment method on the order.
  • reference_id on billing_address, shipping_address, and primary_contact — link inline records to your own system.
  • attributes on the same three objects — custom name/value pairs, both required on each entry.
Changed request validation — update
  • reference_id is no longer required on PUT /v2/orders/{id}.
New response fields — list, create & update
  • type — order or quote.
  • entity_source — where the order originated.
  • reference_id, state_info, and country_info on the addresses and primary contact.
New response fields — detail only
  • customer_reference_id and customer_name — resolved inline, so no second customer call.
  • price_list — the full object (id, name, reference_id) alongside the existing price_list_id.
  • cart_total.
  • created_by and updated_by — user objects with id and email. v1 did not return these.
  • Line items gain id, reference_id, parent_sku_id, final_unit_price, applied_promotion (id, name, reference_id, promo_code), and applied_modifiers (id, name, unique_id, plus a values array of id, value, price, quantity, suffix).
  • Addresses and the primary contact gain an attributes array (id, name, value, created_at, updated_at).
  • Charges gain applied_promotion.
​
New Endpoint
Route: /v2/products
New query parameters — list
  • ids and reference_ids — filter by product UUID or your own product IDs. Both repeatable.
New request fields — create & update
  • brand — associate the product with a brand for filtering and storefront display. Product-level on create; the fields below are per variant.
  • tags — free-form string tags for search and categorisation.
  • seo_info — primary_title, title, description, keywords.
  • url_slug — readable URL path, for example red-wool-rug-5x8.
  • channel_visibility.website — DontShow, ShowForLoggedInUsersOnly, or ShowForLoggedInAndNonLoggedInUsers.
  • volume — physical volume per variant as cft or cbm. If both are sent, cft wins.
New request field — update only
  • grouping_attributes — attributes such as colour or size that group variants under one listing. v1 accepted this on create only.
New request fields — product_prices[]
  • sale_price — promotional price alongside the regular price.
  • default_order_quantity — quantity pre-filled when a buyer adds the product to an order.
  • volume_tiers — tiered pricing by quantity. Each tier takes start_quantity and price (both required) and an optional step_increment, the multiple that ordered quantities must follow within the tier.
New response fields — list
  • priority — display order in a listing; lower values surface first.
  • channel_visibility, volume (cft/cbm), and medias[].order.
New response fields — detail & updateEverything from the list response, plus categories, tags, brand, url_slug, and seo_info. Each price_lists entry also returns sale_price, default_order_quantity, and volume_tiers, where price is the base amount and sale_price the promotional one.
​
New EndpointBreaking
Route: /v2/invoices
Multiple orders per invoice
  • order_ids (array, required) replaces v1’s order_id (string, required) in requests and responses.
Server-calculated total
  • total_amount is no longer accepted. The total comes from items and charges, and is returned in the response.
New and changed query parameters — list
  • ids and invoice_statuses — filter by invoice UUID or detailed status. Both repeatable.
  • status — now PAID or PENDING; v1 used PAID or UNPAID.
New request fields — create & update
  • invoice_status — DRAFT, OPEN, SENT, PARTIALLY_PAID, CLOSED, OVERDUE, CANCELLED, or CREDIT_NOTE_ISSUED.
  • payment_method, payment_terms, po_number, shipping_method, shipped_date, sales_rep_id — commercial and fulfilment details that previously lived outside the invoice.
  • charges — invoice-level charges: name and type required (discount, tax, or shipping), plus value_type (value or percentage) and amount.
  • attributes — custom metadata: name and value required, optional label.
  • items[].tax_charges — per-line breakdown of tax, discount, shipping, and additional charges. Each amount has a matching *_type of value or percentage.
  • items[].item_status — per-line fulfilment: ordered_quantity, shipped_quantity, open_quantity, ship_date, delivered_date, requested_ship_date, requested_delivery_date.
New response fieldsEverything above, plus items[].sku and items[].final_unit_price. Returned attributes also include id, created_by, updated_by, created_at, and updated_at.