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.
POST/account/authenticate/single-use-tokenAuthenticate with Single use Token
Authorization
Body
Exchanges a single-use token (issued by Get Single Use Token) for an authentication ticket, enabling cross-domain magic-link login without re-entering credentials. The token is consumed on use. Returns the 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.
Issues a short-lived, single-use token from an authenticated ticket for handing login off to another domain or context. Returns the bare token string, which is later redeemed via Authenticate with Single use Token.
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.
Searches appointments by a free-text query (for example a guest name or email) and returns the matching appointments. 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.
Creates (or resumes) an admin checkout cart session for a customer and returns the bare session id string (grammar 'Admin-{customer}-{random}'). Pass this id as the X-Session-Id header on all subsequent cart calls.
POST/cart/session/club/{club_id}/{member_id}Create Club Cart Session
Authorization
Parameters
Body
Creates (or resumes) the checkout cart session for a specific club member and returns the bare session id string (grammar 'club-{club}-{member}'). Pass this id as the X-Session-Id header on all subsequent cart calls.
Creates (or resumes) a wishlist/allocation cart session for a customer and returns the bare session id string (grammar 'Wish-{customer}-{order}'). Pass this id as the X-Session-Id header on all subsequent cart calls. Optionally scope to an existing order via the order_id body field.
Parameters
Name
Type
Required
Description
Example
customer_id
number
Required
Customer Id
order_id
number
Optional
Existing order id to scope the wish cart to (optional)
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). Merges the supplied key/value pairs into the cart config. Accepts the full ~40-field config bag (financial toggles/exemptions, discount/promo, order meta/workflow, profile, and shipping-address fields); only the keys you send are updated. There is no server-side whitelist, so send only known keys.
Parameters
Name
Type
Required
Description
Example
order_type
string
Optional
Order type: Admin/Club/Offering/POS or save type corporate/Wish/Saved
tax_exempt
string
Optional
Tax exemption (Yes/No)
crv_exempt
string
Optional
CA redemption value exemption (0/1)
mbd_exempt
string
Optional
Maine bottle deposit exemption (0/1)
payment_exempt
string
Optional
Payment exemption (0/1); routes to Wire for some clients
free_shipping
string
Optional
Free shipping toggle (0/1)
insurance
string
Optional
Shipping insurance toggle (0/1; empty string = not yet set)
disallow_credits
string
Optional
Disallow store credits (0/1)
override_discount
string
Optional
Manual discount override (decimal string or empty)
override_shipping
string
Optional
Manual shipping override (decimal string or empty)
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). Sets the quantity of the line item with the given SKU. Returns the updated cart envelope (price is volume-adjusted by the API).
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.
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). Empties the cart of all line items (releases any reserved inventory). Returns the emptied 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). Selects a saved customer address as the cart ship-to address. 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). Selects a saved customer payment method for the cart. Returns the full 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). Selects a shipping method (by rate/method id) for the cart, recalculating shipping. 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). Returns the shipping methods available for the current cart contents and ship-to address, with computed rates.
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 list of states/regions the current cart is allowed to ship to (compliance-gated by the cart contents).
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). Applies a manual discount override to 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). Applies a manual shipping override to 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). Applies a promo code to the cart, recalculating the discount. 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). Removes any applied promo code 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). Applies a gift card to the cart by code. Returns the updated cart envelope with gift_card_code/gift_card_balance/gift_total populated in config.
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). Looks up a gift card by code (balance and status) without applying it to the cart.
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 any applied gift card 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). Records a partial payment against the cart (e.g. a gift-card charge) toward the total before checkout. Returns the updated cart envelope with the remaining balance.
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). Voids all partial payments recorded against 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). Converts the cart into an order and returns the bare new order id (no envelope); check success/errors separately. The supplied fields are merged over the cart config; club_id/club_name are added for Club orders and actual_ship_date for picked-up orders.
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). Persists the current cart as a saved order of the given type (Saved for pending orders, corporate for gifting) without checking out. Returns the saved order id.
Returns the list of saved carts/orders of the given type for the current customer/session (Saved for pending, Wish for wish requests). 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).
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 allocation structure for the cart's SKUs (a separate structure from core line items): per-SKU min/max wish and quantity limits and the allocation window.
POST/cart/stripe-client-secretGet Stripe Elements Client Secret
Authorization
Body
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). Creates/updates the payment intent for the cart total and returns the bare Stripe Elements client-secret string (empty string on failure). payment_methods defaults to ['card'] plus any enabled wallet/bank methods.
Sends the order cancellation email for the given order id. 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).
Sends (or re-sends) the order receipt/confirmation email for the given order id. 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).
Sends the shipment tracking email for the given order id. 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).
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)
Starts a batch order for the club ({id} is the 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. Mirrors clubs::createOrder.
Discards the club's in-process batch order ({id} is the club id), clearing the saved order_data and the members' reserved carts. Returns true. Mirrors clubs::deleteOrder.
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.
Returns a single hydrated member ({id} is the club, {member_id} the membership). Its data field is a JSON string the API does NOT auto-expand - decode and merge it client-side. Mirrors clubs::getMember.
Returns the club's members ({id} is the club id) as an array of member rows for batch-order review; the JSON data blob is not auto-expanded. Mirrors clubs::getMembers.
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)
Updates a member of club {id} ({member_id} is the membership), reconciling method_id with the delivery preference. Returns the updated member row. Mirrors clubs::updateMember.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Club Id
member_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)
GET/clubMembers/customer/{customer_id}Get Memberships By Customer
Authorization
Parameters
Returns all active club memberships for a customer, keyed by membership 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. created is the signup date.
Creates a historical (already-cancelled) membership, used when importing members that carry a cancellation date. Equivalent to create() but forces email_template='none' and persists the cancellation. Note the cancellation date is dual-columned: the API falls back between cancellation_date and the misspelled legacy cancelation_date.
Points a membership at a cart session id (the club-{club}-{member} reserved batch cart). Used when (re)binding a member's batch cart during the lifecycle.
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.
Updates a member of club {id} ({member_id} is the membership) - method, address, payment, and delivery preference - reconciling method_id. Returns the updated member row. Mirrors clubMembers::update.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Club Id
member_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)
GET/clubs/{id}/members/with-cartsGet Members With Carts
Authorization
Parameters
Returns the club's batch members with each member's reserved cart hydrated under a cart key. Cancelled members are dropped, the JSON data blob is merged up, and derived method, ccNum, and ccType are added. Append an optional status segment (blank/Ready/Complete/Exclude) to filter to a single batch state. Used to drive the batch-order review screen.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Club Id
status
string
Optional
Optional batch status filter: Ready, Complete, or Exclude
POST/clubs/members/{member_id}/errorSet Member Batch Error
Authorization
Parameters
Body
Records (or clears) the batch failure message on a club member row after a failed charge/checkout. Pass an empty message to clear the error. (Legacy passed the message in the URL path; here it is a body field.)
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.
Bulk-hydrate multiple customers in one call by POSTing a bare array of customer ids. Returns a map keyed by customer id. Use this instead of many single GET /customers/{id} calls when rendering lists.
POST/customers/external/{external_id}Create Customer With Id
Authorization
Parameters
Body
Import path that creates a customer keyed to an external system id (e.g. a Cultivate or AMS id) so subsequent syncs are idempotent. Same body as Create Customer; any nested address is stripped and created separately against the Addresses resource.
Returns the highest-value customers ranked by lifetime order total, paginated. Returns a map keyed by customer id including the derived order_total/order_count fields.
POST/customers/clubs/batchGet Customer Clubs By Id
Authorization
Body
Bulk variant of Get Customer Clubs. POST a bare array of customer ids to fetch each customer's club memberships in one call. Returns a map keyed by customer id.
POST/customers/groups/batchGet Customer Groups By Id
Authorization
Body
Bulk variant of Get Customer Groups (getGroupsById). POST a bare array of customer ids to fetch each customer's group memberships in one call. Returns a map keyed by customer id. Note: the per-customer getGroupsByCustomer alias is served by GET /customers/{id}/groups.
GET/customers/{id}/emailsGet Customer Email History
Authorization
Parameters
Returns the log of transactional/marketing emails sent to a customer. Rows are derived from the send log (template, subject, recipient, status, timestamp).
Sends (or re-sends) a signup/welcome email to the customer using the named email template. The template name maps to a content template (e.g. signup, signup-tastingroom).
Generates a preauthorization token for the customer, used for magic/cross-domain links such as cart recovery. Optionally set an expiry window. Returns the token and its expiry.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Customer Id
expires
string
Optional
Optional expiry (Y-m-d H:i:s); defaults to a standard 7-day window
POST/customers/recalculate-order-totalsRecalculate Customer Order Totals
Authorization
Body
Maintenance action that recomputes the derived purchase-history rollups (order_count, order_total, first_purchase_, last_order_) across all customers from their orders. Side-effectful; run as a batch job.
Adds a single per-SKU allocation entry to the customer's individual allocation. Stored inside the customer's individual_allocation JSON. Use Set Customer Individual Allocation to replace the whole set at once.
Replaces the customer's entire individual allocation with the supplied product list in one call (used by allocation import). Each item is a per-SKU allocation entry.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Customer Id
products
array
Required
Array of allocation entries, each with sku, min_quantity, max_quantity, min_wish, max_wish, product_badge
GET/customers/allocation-wish-detailsGet All Allocation Wish Details
Authorization
Returns aggregate individual-allocation and wishlist detail across customers (a report/aggregate read). Each entry mirrors the decoded individual_allocation structure per SKU.
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.
GET/groups/with-customersGet All Groups With Customers
Authorization
Returns all groups, each with a fully hydrated customers array (customer objects, not just ids). Heavier payload; use when you need member details inline.
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.
Bulk-fetch full order objects for an array of order ids in a single call. Use when hydrating a set of orders returned from a list/filter that only carried ids.
List orders created within an inclusive date range (Y-m-d). An optional page size and page number may be appended (/orders/date/{start}/{end}/{limit}/{page}) for pagination.
GET/orders/{id}/transactionsGet Order Transactions
Authorization
Parameters
Return the payment transaction rows (Debit/Refund/Chargeback) recorded against an order. subtotal, co_retail_delivery_fee and shipping_insurance are not on the raw row (added client-side); refunds store negated monetary values with parent_id pointing at the parent Debit.
Create an order that carries a caller-supplied external/legacy id (used by importers and integrations). The order object is posted in the body; the external id is the path segment.
Parameters
Name
Type
Required
Description
Example
external_id
string
Required
External / legacy order id to assign
customer_id
number
Required
Customer Id
order_type
string
Required
Order type: POS, Admin, Offering, Web, Club, Gift, Invoice
status
string
Optional
Order status
shipping_first_name
string
Optional
Shipping recipient first name
shipping_last_name
string
Optional
Shipping recipient last name
shipping_address
string
Optional
Shipping street address
shipping_city
string
Optional
Shipping city
shipping_state
string
Optional
Shipping state (auto-derived from shipping_zip)
shipping_zip
string
Optional
Shipping ZIP
shipping_country
string
Optional
Shipping country
shipping_method
string
Optional
Shipping method name
subtotal
number
Optional
Order subtotal (decimal string)
tax
number
Optional
Tax (includes CO retail delivery fee)
shipping
number
Optional
Shipping (includes insurance)
total
number
Optional
Order total
products
array
Optional
Line items to seed, each {sku, quantity, price, discount}
PUT/orders/{id}/ship-status/{status}Update Ship Status
Authorization
Parameters
Body
Set the order's ship status. Cancelled is reserved for the cancel flow and is blocked here (OFF-536). Setting a shipped status does not itself create tracking (see Add Packages).
Parameters
Name
Type
Required
Description
Example
id
number
Required
Order Id
status
string
Required
New ship status (e.g. Not Shipped, Processing, Hold, Shipped)
PUT/orders/{id}/payment-status/{status}Update Payment Status
Authorization
Parameters
Body
Set the order's payment status. Only selectable payment statuses may be assigned by an admin. Convenience action equivalent to updating the payment_status attribute.
Append line-item rows to an order. Line items are stored as immutable add/remove rows: a negative quantity records a removal, and current quantity per SKU is the signed sum. Adjusts inventory. item_count is always recomputed.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Order Id
products
array
Required
Line-item rows, each {sku, quantity (signed), price, discount}
Resolve tax jurisdiction/rate for a shipping address and merge the resulting tax_* attributes back onto the order. Body fields are remapped from the order's shipping_* fields. The exact returned subset can vary by tax provider.
List saved/pending order cart sessions of a given type (Saved, Wish, or corporate). These are in-progress carts persisted for later checkout, keyed by cart session id.
Update an order note's message and/or category. Notes are typed Log (activity log) or Admin (editable notes panel); category defaults to General (Alert renders a red badge).
Parameters
Name
Type
Required
Description
Example
note_id
number
Required
Note Id
message
string
Optional
Note body (HTML/newlines allowed)
category
string
Optional
Category: General, Engagement, Feedback, Alert, or config-custom
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.
GET/payment/created/{start}/{end}Get Payment Methods By Created Date
Authorization
Parameters
Returns stored payment methods created within the given date range. Useful for reconciling newly added cards. Credit card numbers are returned as the last 4 digits only.
Admin update used to finalize a stored payment method by writing its Stripe tokens. This is the ACH micro-deposit verification path: once a bank account SetupIntent is confirmed, the payment_token and account_token are written to the payment method (the account_token replaces the literal 'pending' placeholder set while ACH verification was outstanding).
ElasticSearch-backed filter. POST an array of clause objects (term, not_terms, range, query_string). Rows joined through other tables may come back with empty ids and should be ignored.
Parameters
Name
Type
Required
Description
Example
type
string
Required
Clause type: term, not_terms, range, or query_string.
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 the inventory adjustment ledger, optionally bounded by a date range. Rows are written straight to CSV, so the exact keys are not guaranteed (inferred below).
Attach an image to a product. Images are stored as full S3 URLs; multi-size sections write four keys ({key}, {key}_large 3000px, {key}_medium 2000px, {key}_small 600px). Use image, image_2, or image_3 as the base key.
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.
Attach an image to a category. Uses the same multi-size convention as products ({key}, {key}_large, {key}_medium, {key}_small). Base keys are image, image_2, image_3.
{
"product_id": "842",
"score": "95",
"reviewer": "James Suckling",
"review": "Full-bodied and structured, with layers of cassis and graphite. A standout vintage."
}
Response
Headers · 200
Content-Type: application/json
Body
{
"id": "57",
"product_id": "842",
"score": "95",
"reviewer": "James Suckling",
"review": "Full-bodied and structured, with layers of cassis and graphite. A standout vintage.",
"sort": "1"
}
POST/reviews/{id}Update Review
Authorization
Parameters
Body
Update a review's score, reviewer, and/or body.
Parameters
Name
Type
Required
Description
Example
id
number
Required
Review Id
score
string
Required
Rating / score (free text, e.g. "95" or "95 pts").
Returns the full customer-referral invite history. Each row carries the inviter (customer_id), the invitee (newcustomer_id), status, the sort timestamp, the first-purchase order_id, and nested customer/newcustomer objects.
Bulk variant of Get Invites By Customer. POST a bare array of inviter customer ids to fetch each customer's sent invites in one call. Returns a map keyed by customer id.
Returns invites sent within the given date range, intended for reporting/export. On export the PAID status is relabeled PURCHASED. Rarely used (legacy export).
Creates a new promotion. The submitted code is slugified to uppercase alphanumeric (spaces, periods and dashes are removed), so "Summer 10" becomes "SUMMER10". New promotions are always created with status Active. Set type to Percentage or Dollar; amount is read as a percent or a dollar value accordingly. multi_use of 1 allows unlimited reuse, 0 restricts the code to a single use. Leave expires empty for a code that never expires.
Parameters
Name
Type
Required
Description
Example
code
string
Required
Promo code entered by the customer at checkout. Slugified to uppercase alphanumeric on save
name
string
Optional
Internal name for the promotion (never shown to the customer)
type
string
Required
Discount type: Percentage or Dollar
amount
string
Required
Discount amount: a percent when type is Percentage, a dollar value when type is Dollar
multi_use
number
Optional
1 for a multi-use code, 0 for a single-use code
starts
string
Optional
Date and time the promotion becomes valid
expires
string
Optional
Date and time the promotion expires; leave empty for no expiration
Returns all abandoned-cart recovery records. Each record is keyed by its checkout session and is enriched with the attached customer (groups pipe-joined), the derived cart total and item_count. Impersonation sessions (Admin- prefix) are excluded.
Returns a single abandoned-cart recovery record by its checkout session id, including the enriched customer, line items, and derived total and item_count.
Archives an abandoned cart, setting its recovery_status to Archived and stamping recovery_date. Archived carts are removed from the active recovery workflow.
Sends a recovery email to the customer for the given abandoned cart using the named email template (for example recovery1, recovery2 or recovery3). The email links the customer back to a preauthenticated recovery URL and sets email_status to Sent.
Parameters
Name
Type
Required
Description
Example
session
string
Required
Checkout session id of the abandoned cart
template
string
Required
Name of the email template to send, e.g. recovery1
Returns all email templates for the account, each with its name, subject and message. Known template names include: appointment-cancellation-01, appointment-confirmation-01, appointment-confirmation-02, appointment-confirmation-03, appointment-decline-01, appointment-reminder-01, cancellation, club-receipt, club-signup, gift-card, receipt, receipt-hospitality, receipt-update-wish, receipt-wish-only, receipt-wishlist, recovery1, recovery2, recovery3, signup, signup-3rd-party, signup-internal, signup-tastingroom, update. A -new suffix denotes a working copy and is stripped before lookup.
[
{
"name": "receipt",
"subject": "Thank you for your order",
"message": "<p>Hi {first_name},</p><p>Thank you for your order. Your wines are on the way.</p>"
},
{
"name": "recovery1",
"subject": "You left something in your cart",
"message": "<p>Hi {first_name},</p><p>You still have items waiting in your cart. <a href=\"{recovery_url}\">Complete your order</a>.</p>"
}
]
GET/content/emails/{name}Get Email Template
Authorization
Parameters
Returns a single email template by name. Known template names include: appointment-cancellation-01, appointment-confirmation-01, appointment-confirmation-02, appointment-confirmation-03, appointment-decline-01, appointment-reminder-01, cancellation, club-receipt, club-signup, gift-card, receipt, receipt-hospitality, receipt-update-wish, receipt-wish-only, receipt-wishlist, recovery1, recovery2, recovery3, signup, signup-3rd-party, signup-internal, signup-tastingroom, update.
{
"name": "receipt",
"subject": "Thank you for your order",
"message": "<p>Hi {first_name},</p><p>Thank you for your order. Your wines are on the way.</p>"
}
POST/content/emails/{name}Save Email Template
Authorization
Parameters
Body
Saves (creates or overwrites) an email template by name, setting its subject and message. Relative href="/..." links in the message are rewritten to absolute URLs using the account website_url. Known template names include: appointment-cancellation-01, appointment-confirmation-01, appointment-confirmation-02, appointment-confirmation-03, appointment-decline-01, appointment-reminder-01, cancellation, club-receipt, club-signup, gift-card, receipt, receipt-hospitality, receipt-update-wish, receipt-wish-only, receipt-wishlist, recovery1, recovery2, recovery3, signup, signup-3rd-party, signup-internal, signup-tastingroom, update.
{
"subject": "Thank you for your order",
"message": "<p>Hi {first_name},</p><p>Thank you for your order. Your wines are on the way.</p>"
}
Response
Headers · 200
Content-Type: application/json
Body
{
"name": "receipt",
"subject": "Thank you for your order",
"message": "<p>Hi {first_name},</p><p>Thank you for your order. Your wines are on the way.</p>"
}
Transactions
GET/transactions/{id}Get Transaction
Authorization
Parameters
Fetch a single payment transaction row by its id, including type (Debit/Refund/Chargeback), gateway, monetary breakdown, and parent linkage.
GET/transactions/date/{start}/{end}Get Transactions By Date
Authorization
Parameters
List payment transactions created within the given date range (day boundaries). Used alongside the datetime variant to reconcile timezone-sensitive reporting.
GET/transactions/datetime/{start}/{end}Get Transactions By Date/Time
Authorization
Parameters
List payment transactions created within the given datetime range. Called back-to-back with the date variant so client reporting can reconcile local vs UTC day boundaries.
GET/transactions/refunds/{order_id}Get Refunds For Order
Authorization
Parameters
Return the Refund and Chargeback rows tied to an order. Netting against the parent Debit is additive per monetary field; each row links to its parent via parent_id.
Record a Debit transaction against an order. Accepts Stripe or Authorize.Net (authnet_*) payment identifiers plus the monetary breakdown. Side effect: when a credits amount is supplied, the customer's store-credit bank must be decremented separately via a credits call — this row only records the amount.
Parameters
Name
Type
Required
Description
Example
order_id
number
Required
Order Id
customer_id
number
Required
Customer Id
credit_type
string
Optional
Card brand, ACH, or GiftCard
account_number
string
Optional
Last 4 of the payment account
account_token
string
Optional
Stripe customer token (or 'pending' for unverified ACH)
payment_token
string
Optional
Stripe payment method token (pm_... / seti_...)
authnet_profile_id
string
Optional
Authorize.Net customer profile id (legacy path)
authnet_payment_id
string
Optional
Authorize.Net payment profile id (legacy path)
account_uri
string
Optional
Gateway account URI
card_uri
string
Optional
Gateway card URI
subtotal
number
Optional
Line subtotal
discount
number
Optional
Discount amount
credits
number
Optional
Store credit applied (bank move happens separately)
Issue a refund against a Debit transaction. Each monetary field is passed negated, and the parent total is passed as amount (the total→amount rename). Optionally flag fraudulent and pass a credits amount only when > 0 (a credits + order_id refund also adjusts the store-credit bank). Store-credit-only refunds bypass this endpoint and credit the bank directly.
GET/giftcards/{id}/transactionsGet Gift Card Transactions
Authorization
Parameters
Return the ledger for a gift card: signed amount rows (+credit / -debit) with the running balance, sorted for history display (created, note, amount, balance). This ledger is distinct from the payment transactions resource.
Issue a new gift card. amount is required and must be > 0; code is auto-generated when omitted. Recipient identity (first/last/email) is not a native field — fold it into note as 'Recipient: {last}, {first} ({email})[ - {note}]'. Side effect: an initial ledger transaction is written, noted 'Initial Balance: ...' (or 'Card Created' when an order exists with no note).
Apply a signed amount to a gift card (negative = debit). The balance can never go negative (the guard rejects balance + amount < 0). A positive credit on a Depleted card flips its status back to Active.
POST/customers/{customer_id}/creditsAdd Store Credit
Authorization
Parameters
Body
Apply a signed adjustment to a customer's store-credit bank (positive = credit/refund, negative = debit). Passed as a body (the legacy transport carried amount and note as URL path segments, which the rebuild moves into the body). Manual adjustments suffix the note with ' --Adjusted by {admin}'.
Parameters
Name
Type
Required
Description
Example
customer_id
number
Required
Customer Id
amount
number
Required
Signed amount (positive = credit, negative = debit)
GET/credits/open/{pageSize}/{lastId}Get All Open Credit
Authorization
Parameters
Keyset-paginated list of customers carrying an open store-credit balance. Pass pageSize and the lastId seen to fetch the next page. Each row's last_credit and last_debit are packed strings in the form 'amount ||| timestamp ||| note' (split client-side on ' ||| '); the empty-result fallback uses {customer_id, amount}.
Parameters
Name
Type
Required
Description
Example
pageSize
number
Required
Number of rows per page
lastId
number
Required
Highest customer id from the previous page (0 to start)
[
{
"id": "1",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"credits": "125.00",
"last_credit": "36.00 ||| 2026-02-16 15:17:00 ||| Refund for order #42",
"last_debit": "-14.00 ||| 2026-01-30 09:12:00 ||| Applied to order #38"
}
]
Rates
GET/rates/methodsGet Shipping Methods
Authorization
Returns all configured shipping methods in sort order. Append a state code (e.g. /rates/methods/CA) to return only the methods available for that destination state. All values wire as strings.
Parameters
Name
Type
Required
Description
Example
state
string
Optional
Optional two-letter destination state to filter methods available in that state
Returns the nested rate grid for a method, shaped { [bottleSize]: { [zone 2-9]: { [numBottles]: rate } } }. The 750mL max-charge thresholds live separately on the method's max_charge JSON.
GET/rates/international/{country}/tableGet International Rate Table
Authorization
Parameters
Returns the international rate grid for a country, shaped { [bottleSize]: { [1..6|12]: price } }. International shipping rules themselves live in config.
POST/rates/international/{country}/tableSave International Rate Table
Authorization
Parameters
Body
Replaces the international rate grid for a country. Post the same { [bottleSize]: { [count]: price } } structure returned by Get International Rate Table.
Parameters
Name
Type
Required
Description
Example
country
string
Required
Country code or name
rates
object
Required
Nested rate grid keyed by bottle size then bottle count
Returns the full flat key/value config store. Boolean config values wire as the literal strings 'TRUE'/'FALSE'; some values (bottle_sizes, cubing_pack_sizes, case_discount_multi) are JSON-encoded strings.
Returns per-state shipping/tax rules, keyed by state code. tax is a percent, tax_shipping and bypass_sc_tax_rates are '1'/'0', ship_dates is a comma-separated date list.