110 endpoints·12 groups·314 documented parameters·Updated October 9, 2026
Welcome to the Offset Management API documentation. This API can be used for creating merchant facing applications powered by the Offset platform.
Headers
There are 2 HTTP Headers used by the management API:
Content-Type
X-Auth-Token
The Content-Type header is a standard header and should be set to application/json for all requests.
The X-Auth-Token header is used to authenticate with the API server.
Getting Started
Every request needs an API key. An authorized user can provision one in Offset Commerce under Settings › More › API Keys. No account, or need a hand? Email developer@offsetpartners.com.
Thank you for choosing Offset to power your wine business.
Authentication
There are 3 endpoints used for authenticating with the API:
The Authenticate User method allows authentication provided a valid administrator username and password. Along with basic profile information this method returns a Ticket which can be used with the method Get Account Auth Token to obtain an Auth Token which can be passed in the X-Auth-Token Header to allow API access for an account. If you already know what account you want to access you can do this in a single step by supplying the account you wish to access as well using the optional account field.
2 Factor Authentication
The Authenticate User 2 Factor Auth method allows authentication for administrators who have optionaly enabled the 2 Factor Auth feature. If 2FA is enabled then the response from Authenticate User will have the 2FA "Token" and an additional field "require_2fa" which will be set to 1. The 2FA Token along with the 2FA Code that was sent directly to the administrator can be sumitted using Authenticate User 2 Factor Auth to complete the Authentication process and return an Authentication Ticket which can be supplied to Get Account Auth Token.
Get Account Auth Token
The Get Account Auth Token method takes an Authentication Ticket supplied by the Authenticate User method and an account you wish to access and returns an Auth Token that can be passed in the X-Auth-Token header to allow access to an account via the API.
Errors
The API uses standard HTTP status codes. A successful request returns 200 OK. Any other status code indicates an error, and the response body contains a JSON object wrapping a ServerFault with a numeric code and a human-readable details message:
400 — Bad Request (malformed request or failed validation)
401 — Unauthorized (missing, invalid, or expired X-Auth-Token)
404 — Not Found (the requested resource does not exist)
500 — Server Fault (an unexpected server error occurred)
A 401 response means the authentication token is no longer valid. Obtain a new token via the Authentication endpoints before retrying the request.
Pagination
List endpoints that can return large result sets accept limit and page parameters. The page index is zero-based — the first page is page 0. To retrieve an entire collection, request successive pages until a page returns fewer than limit records:
GET /customers/5000/0
GET /customers/5000/1
...
A few high-volume endpoints use keyset (cursor) pagination instead, taking a pageSize and the lastId returned by the previous page (for example, Get All Open Credit). Continue requesting pages, passing the last id from each response, until an empty page is returned.
Conventions
Account Scope
Every request operates in the context of a single merchant account. The account is bound to your X-Auth-Token (obtained via the Authentication endpoints); some deployments also accept an X-Auth-Account header to select the account explicitly.
Data Types
For compatibility, most scalar values are transmitted as JSON strings, including numbers and identifiers. Monetary amounts are decimal strings such as "36.00". Timestamps use the format YYYY-MM-DD HH:MM:SS (for example "2026-02-16 15:17:00"); date-only fields use YYYY-MM-DD.
Booleans
Boolean-style fields are not uniform across resources: many use the strings "Yes" / "No", some use "1" / "0", and account configuration flags use "TRUE" / "FALSE". Refer to each field's description for its expected values.
Filtering
Endpoints named Filter (for example Filter Customers, Filter Orders, Filter Products) accept an ElasticSearch-style list of query clauses in the request body, plus a set of special keys that are resolved server-side (such as groups, clubs, tags, and shipping states).
Account
Resources related to Account.
POST/account/authenticateAuthenticate User
Authorization
Body
Authenticates a user by username and password (optionally scoped to an account) against the auth server and returns an authentication ticket, the user profile, and the accounts they can access. This is the first step of login; if the account requires two-factor auth, follow up with Authenticate User 2 Factor Auth before exchanging the ticket for an account token via Get Account Auth Token.
POST/account/authenticate/2faAuthenticate User 2 Factor Auth
Authorization
Body
Completes two-factor authentication by submitting the ticket from the initial authenticate step together with the user's 2FA pin. Returns the verified ticket, profile, and accessible accounts.
Exchanges an authentication ticket for an account-scoped access token for the named account, returning the token and account details. This token is the value passed as the X-Auth-Token header on all subsequent Management API calls.
Creates a new address for a customer (customer_id required) and returns the created record, including its new id and server-computed fields such as geocode coordinates and the residential and verified flags.
Creates a tasting-room appointment for a customer at the given timestamp and returns the created appointment. status is one of Requested, Pending, Waitlist, Confirmed, Declined, Cancelled, No Show or Checked In; category is one of Consumer Acquisition, Consumer Conversion, Consumer Retention, Trade or Industry. Up to 20 product SKUs may be attached as wine_1 through wine_20.
{
"id": 35,
"customer_id": 1,
"timestamp": "2020-07-31 11:00:00",
"status": "Requested",
"page_source": "Visit",
"created_by": "Customer",
"ip_address": "5.42.254.123",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@gmail.com",
"mobile_phone": "7075551234",
"alternate_date": "01/10/2021",
"preferred_time": "Morning",
"appointment_type": "Winery Tour & Tasting",
"size": "2",
"guests": "John DoernJane Doe",
"customer_comments": "I understand the tasting is unavailable to us (as members awaiting allocation), and I hope the Monday appointment is available. Thanks in advance!",
"name": "Jon Doe",
"customer_first_name": "Jon",
"cancellation_reason": "",
"customer_last_name": "Doe",
"customer_phone": "7075551234",
"customer_email": "john.doe@gmail.com",
"hour": "10:00 AM",
"endtime": "11:30 AM",
"host": "",
"room": "Foyer Lounge",
"reason": "Waiting List",
"category": "Consumer Conversion",
"notes": "Very kind, read the rules and requested a monday morning. Offered the 10am time slot."
}
PUT/appointments/{id}Update Appointment
Authorization
Parameters
Body
Updates the given appointment, for example to reschedule its timestamp or change its status. status is one of Requested, Pending, Waitlist, Confirmed, Declined, Cancelled, No Show or Checked In. Returns true on success.
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Returns the full cart envelope: config, items keyed by SKU, shipment, and the monetary totals which are top-level siblings of config/items/shipment (not nested under a totals key).
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Returns just the cart config sub-object (the free-form key/value bag of ~40 order, exemption, discount, and shipping-address fields).
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Returns a compact totals summary. Separate from Get Cart; used by gift-card partial-pay and batch-order flows.
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Returns current on-hand inventory for the SKUs in the cart, keyed by SKU, so the client can validate availability before checkout.
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Adds a product to the cart (upsert by SKU: re-adding an existing SKU updates it). Returns the updated cart envelope.
Parameters
Name
Type
Required
Description
Example
sku
string
Required
Product SKU
quantity
number
Required
Quantity
price
string
Optional
Unit price (decimal string; volume-adjusted by the API on read-back)
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Removes the line item with the given SKU from the cart. Returns the updated cart envelope.
Operates on the cart session identified by the X-Session-Id request header (the bare session id returned by Create Admin/Club/Wish Cart Session). Overrides the unit price of the line item with the given SKU. Returns the updated cart envelope.
Cancels a membership by id, setting canceled to 1 and stamping cancellation_date plus an optional cancellation_reason (Personal | Health | Too much wine | Financial | Moving | No longer interested | Other, or a custom value). Returns the updated member row.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Club Member Id
cancellation_reason
string
Optional
Cancellation reason (Personal | Health | Too much wine | Financial | Moving | No longer interested | Other)
Creates a club membership for a customer, affixing a shipping/pickup method, ship-to address, and payment method; delivery_preference is reconciled with method_id and created becomes the signup date. Returns the new member row, including its reserved club-{club}-{member} cart session.
Parameters
Name
Type
Required
Description
Example
customer_id
number
Required
Customer Id
club_id
number
Required
Club Id
method_id
number
Optional
Shipping/pickup method id
address_id
number
Optional
Ship-to address id
payment_id
number
Optional
Payment method id affixed to the membership
signup_type
string
Optional
Web | Tasting Room | Phone (+ custom)
is_gift
string
Optional
Yes | No
email_template
string
Optional
'' (Welcome) | none
delivery_preference
string
Optional
shipping | pickup
method_id_shipping
number
Optional
Shipping method id (when delivery_preference=shipping)
method_id_pickup
number
Optional
Pickup method id (when delivery_preference=pickup)
Returns a single membership by id. Many attributes live inside the JSON data blob, which the API does NOT auto-expand for club members - decode and merge it client-side.
Returns every club membership across all clubs as an array of member rows. The per-member JSON data blob is not auto-expanded and must be decoded client-side.
Reinstates a cancelled membership, clearing canceled back to 0 and its cancellation fields. Note a resumed member may retain canceled = '0' alongside a sentinel 0000-00-00 00:00:00 cancellation date. Returns the updated member row.
Updates a membership (method, address, payment, delivery preference, admin comments, etc.), resolving method_id from delivery_preference and migrating the reserved cart session when club_id changes. Returns the updated member row.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Club Member Id
customer_id
number
Required
Customer Id
club_id
number
Required
Club Id
method_id
number
Optional
Shipping/pickup method id
address_id
number
Optional
Ship-to address id
payment_id
number
Optional
Payment method id affixed to the membership
signup_type
string
Optional
Web | Tasting Room | Phone (+ custom)
is_gift
string
Optional
Yes | No
email_template
string
Optional
'' (Welcome) | none
delivery_preference
string
Optional
shipping | pickup
method_id_shipping
number
Optional
Shipping method id (when delivery_preference=shipping)
method_id_pickup
number
Optional
Pickup method id (when delivery_preference=pickup)
Creates a club definition from the edit-form fields: name, status (Active | Inactive | Test Mode), website description/benefits/price-range, confirmation message, and the discount/free_shipping applied to subsequent non-club orders. signup_groups is a CSV of customer group ids joined on signup. Returns the new club with derived member_count.
Parameters
Name
Type
Required
Description
Example
name
string
Required
Club Name
status
string
Optional
Active | Inactive | Test Mode
description
string
Optional
Website description (HTML)
club_info_1
string
Optional
Website benefits (HTML)
club_info_2
string
Optional
Price range label
club_confirmation_message
string
Optional
Post-signup thank-you (HTML)
discount
number
Optional
Discount percent applied to subsequent non-club orders
free_shipping
boolean
Optional
Free shipping on subsequent non-club orders (1|0)
signup_groups
string
Optional
Comma-separated customer group ids joined on signup
Starts a batch order for club {id} from a subtotal, shipping method, discount, and items[] payload, fanning out one reserved cart per club member. Returns the club id, an order_status flag, the carts_created count, and the requested ship date.
Returns a single club definition by id, including derived member_count. order_status is truthy while a batch order is in process, and order_data holds the saved batch as a JSON string the API strips backslashes from (repair it client-side).
Returns a single hydrated member of club {id} ({member_id} is the membership). Its data field is a JSON string the API does NOT auto-expand - decode and merge it client-side.
Returns the club's members as an array of member rows, used to drive the batch-order review. Append an optional status segment (blank | Ready | Complete | Exclude) to filter to a single batch state; the JSON data blob is not auto-expanded.
Creates a customer and returns the new customer object. Requires first_name, last_name, email, and password; groups are not accepted here (assign them separately, and the account's default_group is added automatically).
Returns customers matching a posted list of ElasticSearch-style clauses (term, not_terms, range, query_string) plus special server-side keys (groups, clubs, tags, order_skus, billing/shipping states, zip_codes, credits). Results are keyed by id; rows lacking an id are dropped.
Full-text search across customers (name, email, and related fields), returning matches keyed by id. For structured criteria use the filter endpoint instead.
Updates the supplied fields on a customer and returns the full updated object. Derived fields (order counts/totals, first-purchase, timestamps) are read-only and ignored if sent.
Adds a note to the customer. type selects Log (activity log) or Admin (notes panel, the default); category defaults to General. Returns the created note.
Creates a customer group and returns the new group object. name is required; status and description are optional. type distinguishes a standard group from an allocation group (whose per-SKU allocation items are managed separately).
Updates the supplied fields on a group and returns the full updated object. Fields include exclusive_access and exclusive_methods gating; archiving a group force-sets exclusive_access to No.
Returns the group's allocation product list, keyed by SKU. Note quantity is the per-customer Max Purchase (NOT inventory - a common trap) and min_quantity is Min Purchase. Rows come back in sort order; name, inventory, increment, and bottle_size are augmented on read.
POST/groups/{id}/allocationAdd Group Allocation Item
Authorization
Parameters
Body
Adds (or updates) an allocation product on the group. quantity sets the per-customer Max Purchase and min_quantity the Min Purchase; min_wish/max_wish bound wishlist quantities.
Cancels the order (not a hard delete), running the cancel flow that restores inventory and voids/refunds transactions as applicable. This is the only path that sets the reserved Cancelled ship status; returns true.
Returns orders matching a posted list of ElasticSearch-style clauses (term, terms, range, query_string, etc.) plus special server-side keys (skus, skus_all, query, order_tags, customer_tags, customer_groups, customer_source, transaction_date). Rows lacking an id are dropped client-side.
Updates the supplied fields on an order (status, ship_status, addresses, dates, notes, etc.) and returns true. item_count is always recomputed from line items and never trusted from the payload; the Cancelled ship status is reserved for the cancel flow and rejected here.
[
{
"id": "4",
"customer_id": "42",
"created": "2018-04-19 09:14:09",
"type": "Admin",
"user_id": "1",
"user_name": "Jane Doe",
"message": "John is a Great Customer!"
},
{
"id": "1",
"customer_id": "42",
"created": "2018-04-19 09:09:51",
"type": "Admin",
"user_id": "1",
"user_name": "Jane Doe",
"message": "John would like to ship FedEx if possible."
}
]
PUT/orders/{id}/packagesAdd Packages
Authorization
Parameters
Body
Adds one or more tracking packages (PascalCase keys: TrackingNumber, Carrier, ShipMethod, DateShipped, etc.) to the order. Recording a package co-updates the order, setting ship_status to Shipped and actual_ship_date to DateShipped; returns true.
Update a standard order's attributes (status, ship_status, payment_status, compliance, addresses, monetary fields, etc.). This is the canonical order update; the POS-context variant is documented separately as "Update Order" (PUT /pos/orders/{id}). Update writable order attributes. Setting ship_status to Cancelled is rejected here (reserved for the cancel flow, OFF-536); compliance may be re-checked on update when configured.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Order Id
status
string
Optional
Order status
ship_status
string
Optional
Ship status (Cancelled not settable here)
order_type
string
Optional
Order type
order_source
string
Optional
Order source
actual_ship_date
string
Optional
Actual ship date (Y-m-d)
cancelled_date
string
Optional
Cancelled date
cancellation_reason
string
Optional
Cancellation reason
compliance_status
string
Optional
Compliance status (_null/Compliant/Not Compliant/Override/Bypass Compliance)
Creates a stored, tokenized payment method for a customer from a Stripe card_token; raw card numbers are never stored, so credit_number holds only the last four digits. Returns the created payment method record.
Create a product. Server generates starting_quantity (= quantity), and derives status/seo_slug when omitted. Gift-card SKUs additionally force tax/credits/shipping/is_gift_card flags.
Parameters
Name
Type
Required
Description
Example
sku
string
Required
Unique SKU. Non-[A-Za-z0-9-] characters are replaced with '-' on write.
name
string
Required
Product name (required).
subtitle
string
Optional
Subtitle / appellation line.
quantity
number
Required
On-hand quantity (required).
price
string
Required
Sale price as a decimal string (required).
retail_price
string
Optional
Compare-at / retail price.
cost
string
Optional
Unit cost.
status
string
Optional
Active (Visible), Inactive (Hidden), or Archived. Defaults to Inactive on create.
website_visibility
string
Optional
On or Off.
product_type
string
Optional
Wine, General Merchandise, Food, Event, Tasting, Gift Card, Collateral, Packaging, Other.
sc_product_type
string
Optional
ShipCompliant type: Wine, Sparkling Wine, Fortified Wine, Food, Freight, General Merchandise, General Non Taxable.
Return all categories. Pass an optional status query filter (Active or Inactive). Categories are flat (no parent) — hierarchy is expressed via product-to-category membership.