Request Offset API Key

Offset Management API

BASE URL https://api.securecheckout.com/v1/

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:

Authenticate User

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:

{
    "ServerFault": {
        "code": 401,
        "details": "Invalid or expired authentication token."
    }
}

Common error codes:

  • 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/authenticate Authenticate User

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.

Parameters
NameTypeRequiredDescriptionExample
account string Optional Account Name
password string Required Customer Password
username string Required Customer Username
Examples
Request
POST/account/authenticate
Headers
Content-Type: application/json
Body
{
    "username": "example@figurecommerce.com",
    "password": "XXXXXX"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "ticket": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "profile": {
        "id": "42",
        "email": "example@figurecommerce.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "created": "2013-09-03 09:02:07"
    },
    "accounts": {
        "209": {
            "id": "209",
            "app": "pos",
            "account": "figureapi",
            "name": "Figure Commerce"
        }
    }
}
POST /account/authenticate/2fa Authenticate User 2 Factor Auth

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.

Parameters
NameTypeRequiredDescriptionExample
pin string Required 2FA Code
ticket string Required Customer Authentication Token
Examples
Request
POST/account/authenticate/2fa
Headers
Content-Type: application/json
Body
{
    "ticket": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "pin": "123456"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "ticket": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "profile": {
        "id": "42",
        "email": "example@figurecommerce.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "created": "2013-09-03 09:02:07"
    },
    "accounts": {
        "209": {
            "id": "209",
            "app": "pos",
            "account": "figureapi",
            "name": "Figure Commerce"
        }
    }
}
POST /account/authorize Get Account Auth Token

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.

Parameters
NameTypeRequiredDescriptionExample
account string Required Account Name
ticket string Required Customer Authentication Token
Examples
Request
POST/account/authorize
Headers
Content-Type: application/json
Body
{
    "ticket": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "account": "figureapi"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "account": {
        "id": "209",
        "name": "Figure API Demo",
        "account": "figureapi",
        "created": "2018-02-13 09:15:56"
    }
}

Addresses

Resources related to Addresses.

POST /addresses Create Address

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.

Parameters
NameTypeRequiredDescriptionExample
address string Required Street Address
address_2 string Optional Unit Number
city string Required City
customer_id number Required Customer Id
first_name string Required Receipient First Name
last_name string Required Recipient Last Name
phone string Optional Recipient Phone Number
state string Required State
title string Optional Address Title
zip string Required Zip Code
Examples
Request
POST/addresses
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "first_name": "Jane",
    "last_name": "Doe",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "email": "example@commercebyfigure.com",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "3989",
    "hash": "0000000000000000000000000000000000000000",
    "created": "2018-03-05 22:03:28",
    "last_update": "2018-04-20 20:48:32",
    "title": "",
    "first_name": "Jane",
    "last_name": "Doe",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "email": "",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "zip_ext": "3302",
    "country": "US",
    "lat": "38.30000000",
    "long": "-122.30000000",
    "residential": "1",
    "verified": "1",
    "customer_id": "42",
    "default": "1",
    "public": "0"
}
DELETE /addresses/{id} Delete Address

Deletes the address with the given id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Address Id
Examples
Request
DELETE/addresses/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /addresses/{id} Get Address

Returns a single address record by id.

Parameters
NameTypeRequiredDescriptionExample
id number Required Address Id
Examples
Request
GET/addresses/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "3989",
    "hash": "0000000000000000000000000000000000000000",
    "created": "2018-03-05 22:03:28",
    "last_update": "2018-04-20 20:48:32",
    "title": "",
    "first_name": "Jane",
    "last_name": "Doe",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "email": "",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "zip_ext": "3302",
    "country": "US",
    "lat": "38.30000000",
    "long": "-122.30000000",
    "residential": "1",
    "verified": "1",
    "customer_id": "42",
    "default": "1",
    "public": "0"
}
GET /addresses/customer/{customer_id} Get Addresses By Customer

Returns all saved addresses for the given customer, keyed by address id.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
Examples
Request
GET/addresses/customer/{customer_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "3989": {
        "id": "3989",
        "hash": "0000000000000000000000000000000000000000",
        "created": "2018-03-05 22:03:28",
        "last_update": "2018-04-20 20:48:32",
        "title": "",
        "first_name": "Jane",
        "last_name": "Doe",
        "birthday": "1980-01-01",
        "company": "Figure Commerce",
        "phone": "7075558520",
        "email": "",
        "address": "100 Main St",
        "address_2": "",
        "city": "Napa",
        "state": "CA",
        "zip": "94559",
        "zip_ext": "3302",
        "country": "US",
        "lat": "38.30000000",
        "long": "-122.30000000",
        "residential": "1",
        "verified": "1",
        "customer_id": "42",
        "default": "1",
        "public": "0"
    }
}
GET /addresses/{limit}/{page} Get All Addresses

Returns a paginated list of all addresses, keyed by id. Pagination is 0-based, so page 0 is the first page.

Examples
Request
GET/addresses/{limit}/{page}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "3989": {
        "id": "3989",
        "hash": "0000000000000000000000000000000000000000",
        "created": "2018-03-05 22:03:28",
        "last_update": "2018-04-20 20:48:32",
        "title": "",
        "first_name": "Jane",
        "last_name": "Doe",
        "birthday": "1980-01-01",
        "company": "Figure Commerce",
        "phone": "7075558520",
        "email": "",
        "address": "100 Main St",
        "address_2": "",
        "city": "Napa",
        "state": "CA",
        "zip": "94559",
        "zip_ext": "3302",
        "country": "US",
        "lat": "38.30000000",
        "long": "-122.30000000",
        "residential": "1",
        "verified": "1",
        "customer_id": "42",
        "default": "1",
        "public": "0"
    }
}
GET /addresses/customer/{customer_id}/default Get Default Customer Address

Returns the customer's default (ship-to) address.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
Examples
Request
GET/addresses/customer/{customer_id}/default
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "3989",
    "hash": "0000000000000000000000000000000000000000",
    "created": "2018-03-05 22:03:28",
    "last_update": "2018-04-20 20:48:32",
    "title": "",
    "first_name": "Jane",
    "last_name": "Doe",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "email": "",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "zip_ext": "3302",
    "country": "US",
    "lat": "38.30000000",
    "long": "-122.30000000",
    "residential": "1",
    "verified": "1",
    "customer_id": "42",
    "default": "1",
    "public": "0"
}
PUT /addresses/customer/{customer_id}/default/{id} Set Default Customer Address

Marks the given address as the customer's default ship-to address. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
id number Required Address Id
Examples
Request
PUT/addresses/customer/{customer_id}/default/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /addresses/{id} Update Address

Updates the given address with the supplied fields (only the keys sent are changed) and returns the updated record.

Parameters
NameTypeRequiredDescriptionExample
address string Optional Street Address
address_2 string Optional Unit Number
city string Optional City
company string Optional Company Name
first_name string Optional First Name
last_name string Optional Last Name
phone string Optional Phone Number
state string Optional State
title string Optional Address Title
zip string Optional Zip Code
id number Required Address Id
Examples
Request
PUT/addresses/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "address": "100 Main St",
    "city": "Napa",
    "state": "CA"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "3989",
    "hash": "0000000000000000000000000000000000000000",
    "created": "2018-03-05 22:03:28",
    "last_update": "2018-04-20 20:48:32",
    "title": "",
    "first_name": "Jane",
    "last_name": "Doe",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "email": "",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "zip_ext": "3302",
    "country": "US",
    "lat": "38.30000000",
    "long": "-122.30000000",
    "residential": "1",
    "verified": "1",
    "customer_id": "42",
    "default": "1",
    "public": "0"
}

Appointments

Resources related to Appointments.

POST /appointments Create Appointment

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.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
status string Optional Appointment Status
timestamp string Required Appointment Time
Examples
Request
POST/appointments
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "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."
}
Response
Headers · 200
Content-Type: application/json
Body
"35"
DELETE /appointments/{id} Delete Appointment

Deletes the appointment with the given id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Appointment Id
Examples
Request
DELETE/appointments/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /appointments/after/{start} Get All Appointments After Date

Returns all appointments scheduled on or after the given date/time.

Parameters
NameTypeRequiredDescriptionExample
start string Required Appointment Date
Examples
Request
GET/appointments/after/{start}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "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."
    }
]
GET /appointments/before/{end} Get All Appointments Before Date

Returns all appointments scheduled on or before the given date/time.

Parameters
NameTypeRequiredDescriptionExample
end string Required Appointment Date
Examples
Request
GET/appointments/before/{end}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "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."
    }
]
GET /appointments/{start}/{end} Get All Appointments in Date Range

Returns all appointments scheduled between the given start and end date/times.

Parameters
NameTypeRequiredDescriptionExample
end string Required Appointments End Date
start string Required Appointments Start Date
Examples
Request
GET/appointments/{start}/{end}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "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."
    }
]
GET /appointments/{id} Get Appointment

Returns a single appointment by id.

Parameters
NameTypeRequiredDescriptionExample
id number Required Appointment Id
Examples
Request
GET/appointments/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "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

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Appointment Id
Examples
Request
PUT/appointments/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "timestamp": "2020-07-31 13:30:00",
    "status": "Confirmed"
}
Response
Headers · 200
Content-Type: application/json
Body
true

Cart

Resources related to Cart.

GET /cart Get 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). 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).

Examples
Request
GET/cart
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "config": {
        "order_type": "Admin",
        "customer_id": "42",
        "tax_exempt": "No",
        "free_shipping": "0",
        "tax_rate": "8.25",
        "promo_code": "",
        "payment_type": "",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_address": "123 Vine St",
        "shipping_city": "Napa",
        "shipping_state": "CA",
        "shipping_zip": "94558",
        "shipping_country": "US",
        "shipping_method": "3",
        "address_id": "1201",
        "payment_id": "880"
    },
    "items": {
        "CAB-EST-2019": {
            "sku": "CAB-EST-2019",
            "name": "Estate Cabernet Sauvignon",
            "subtitle": "2019 750ml",
            "quantity": "6",
            "price": "72.00",
            "discount": "0.00",
            "bottle_size": "750ml",
            "bottle_count": "6",
            "discount_eligible": "Yes",
            "tax_exempt": "No",
            "shipping_included": "0",
            "product_type": "Wine",
            "expires": "0000-00-00 00:00:00"
        }
    },
    "shipment": {
        "address": {
            "id": "1201",
            "first_name": "Jane",
            "last_name": "Doe",
            "address": "123 Vine St",
            "city": "Napa",
            "state": "CA",
            "zip": "94558",
            "country": "US",
            "phone": "707-555-0134",
            "default": "Yes"
        },
        "method": {
            "id": "3",
            "name": "Ground",
            "code": "GND"
        }
    },
    "item_count": 6,
    "subtotal": "432.00",
    "discount": "0.00",
    "credits": "0.00",
    "ca_redemption_value": "0.60",
    "co_retail_delivery_fee": "0.00",
    "me_bottle_deposit": "0.00",
    "tax": "35.64",
    "shipping": "25.00",
    "shipping_insurance": "0.00",
    "tip": "0.00",
    "total": "492.64"
}
GET /cart/config Get Cart 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). Returns just the cart config sub-object (the free-form key/value bag of ~40 order, exemption, discount, and shipping-address fields).

Examples
Request
GET/cart/config
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "order_type": "Admin",
    "customer_id": "42",
    "tax_exempt": "No",
    "free_shipping": "0",
    "tax_rate": "8.25",
    "promo_code": "",
    "payment_type": "",
    "shipping_first_name": "Jane",
    "shipping_last_name": "Doe",
    "shipping_address": "123 Vine St",
    "shipping_city": "Napa",
    "shipping_state": "CA",
    "shipping_zip": "94558",
    "shipping_country": "US",
    "shipping_method": "3",
    "address_id": "1201",
    "payment_id": "880"
}
GET /cart/totals Get Cart Totals

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.

Examples
Request
GET/cart/totals
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "subtotal": "432.00",
    "tax": "35.64",
    "shipping": "25.00",
    "discount": "0.00",
    "total": "492.64",
    "tax_rate": "8.25"
}
GET /cart/inventory Get Cart Inventory

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.

Examples
Request
GET/cart/inventory
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "CAB-EST-2019": {
        "sku": "CAB-EST-2019",
        "quantity": "48",
        "location": "Main",
        "bin_location": "A-12"
    }
}
POST /cart/items Add Cart Item

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
NameTypeRequiredDescriptionExample
sku string Required Product SKU
quantity number Required Quantity
price string Optional Unit price (decimal string; volume-adjusted by the API on read-back)
description string Optional Line-item description
bottle_count number Optional Bottle count
expires string Optional Expiration datetime (0000-00-00... = none; drives cart expiry)
name string Optional Product name
subtitle string Optional Product subtitle
min_purchase number Optional Minimum purchase quantity
max_purchase number Optional Maximum purchase quantity
club_id number Optional Associated club id
club_member_id number Optional Associated club member id
tax_exempt string Optional Line-item tax exemption (Yes/No)
shipping_included string Optional Shipping included in price (0/1)
product_type string Optional Product type ('Gift Card' gates CO retail delivery fee)
discount string Optional Line-item discount
Examples
Request
POST/cart/items
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "sku": "CAB-EST-2019",
    "quantity": 6,
    "price": "72.00",
    "name": "Estate Cabernet Sauvignon",
    "subtitle": "2019 750ml",
    "product_type": "Wine",
    "bottle_count": 6
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "config": {
        "order_type": "Admin",
        "customer_id": "42",
        "tax_exempt": "No",
        "free_shipping": "0",
        "tax_rate": "8.25",
        "promo_code": "",
        "payment_type": "",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_address": "123 Vine St",
        "shipping_city": "Napa",
        "shipping_state": "CA",
        "shipping_zip": "94558",
        "shipping_country": "US",
        "shipping_method": "3",
        "address_id": "1201",
        "payment_id": "880"
    },
    "items": {
        "CAB-EST-2019": {
            "sku": "CAB-EST-2019",
            "name": "Estate Cabernet Sauvignon",
            "subtitle": "2019 750ml",
            "quantity": "6",
            "price": "72.00",
            "discount": "0.00",
            "bottle_size": "750ml",
            "bottle_count": "6",
            "discount_eligible": "Yes",
            "tax_exempt": "No",
            "shipping_included": "0",
            "product_type": "Wine",
            "expires": "0000-00-00 00:00:00"
        }
    },
    "shipment": {
        "address": {
            "id": "1201",
            "first_name": "Jane",
            "last_name": "Doe",
            "address": "123 Vine St",
            "city": "Napa",
            "state": "CA",
            "zip": "94558",
            "country": "US",
            "phone": "707-555-0134",
            "default": "Yes"
        },
        "method": {
            "id": "3",
            "name": "Ground",
            "code": "GND"
        }
    },
    "item_count": 6,
    "subtotal": "432.00",
    "discount": "0.00",
    "credits": "0.00",
    "ca_redemption_value": "0.60",
    "co_retail_delivery_fee": "0.00",
    "me_bottle_deposit": "0.00",
    "tax": "35.64",
    "shipping": "25.00",
    "shipping_insurance": "0.00",
    "tip": "0.00",
    "total": "492.64"
}
DELETE /cart/items/{sku} Remove Cart Item

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.

Parameters
NameTypeRequiredDescriptionExample
sku string Required Product SKU
Examples
Request
DELETE/cart/items/{sku}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "config": {
        "order_type": "Admin",
        "customer_id": "42",
        "tax_exempt": "No",
        "free_shipping": "0",
        "tax_rate": "8.25",
        "promo_code": "",
        "payment_type": "",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_address": "123 Vine St",
        "shipping_city": "Napa",
        "shipping_state": "CA",
        "shipping_zip": "94558",
        "shipping_country": "US",
        "shipping_method": "3",
        "address_id": "1201",
        "payment_id": "880"
    },
    "items": {
        "CAB-EST-2019": {
            "sku": "CAB-EST-2019",
            "name": "Estate Cabernet Sauvignon",
            "subtitle": "2019 750ml",
            "quantity": "6",
            "price": "72.00",
            "discount": "0.00",
            "bottle_size": "750ml",
            "bottle_count": "6",
            "discount_eligible": "Yes",
            "tax_exempt": "No",
            "shipping_included": "0",
            "product_type": "Wine",
            "expires": "0000-00-00 00:00:00"
        }
    },
    "shipment": {
        "address": {
            "id": "1201",
            "first_name": "Jane",
            "last_name": "Doe",
            "address": "123 Vine St",
            "city": "Napa",
            "state": "CA",
            "zip": "94558",
            "country": "US",
            "phone": "707-555-0134",
            "default": "Yes"
        },
        "method": {
            "id": "3",
            "name": "Ground",
            "code": "GND"
        }
    },
    "item_count": 6,
    "subtotal": "432.00",
    "discount": "0.00",
    "credits": "0.00",
    "ca_redemption_value": "0.60",
    "co_retail_delivery_fee": "0.00",
    "me_bottle_deposit": "0.00",
    "tax": "35.64",
    "shipping": "25.00",
    "shipping_insurance": "0.00",
    "tip": "0.00",
    "total": "492.64"
}
PUT /cart/items/{sku}/price/{price} Update Item Price

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.

Parameters
NameTypeRequiredDescriptionExample
sku string Required Product SKU
price string Required New unit price (decimal string)
Examples
Request
PUT/cart/items/{sku}/price/{price}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "config": {
        "order_type": "Admin",
        "customer_id": "42",
        "tax_exempt": "No",
        "free_shipping": "0",
        "tax_rate": "8.25",
        "promo_code": "",
        "payment_type": "",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_address": "123 Vine St",
        "shipping_city": "Napa",
        "shipping_state": "CA",
        "shipping_zip": "94558",
        "shipping_country": "US",
        "shipping_method": "3",
        "address_id": "1201",
        "payment_id": "880"
    },
    "items": {
        "CAB-EST-2019": {
            "sku": "CAB-EST-2019",
            "name": "Estate Cabernet Sauvignon",
            "subtitle": "2019 750ml",
            "quantity": "6",
            "price": "72.00",
            "discount": "0.00",
            "bottle_size": "750ml",
            "bottle_count": "6",
            "discount_eligible": "Yes",
            "tax_exempt": "No",
            "shipping_included": "0",
            "product_type": "Wine",
            "expires": "0000-00-00 00:00:00"
        }
    },
    "shipment": {
        "address": {
            "id": "1201",
            "first_name": "Jane",
            "last_name": "Doe",
            "address": "123 Vine St",
            "city": "Napa",
            "state": "CA",
            "zip": "94558",
            "country": "US",
            "phone": "707-555-0134",
            "default": "Yes"
        },
        "method": {
            "id": "3",
            "name": "Ground",
            "code": "GND"
        }
    },
    "item_count": 6,
    "subtotal": "432.00",
    "discount": "0.00",
    "credits": "0.00",
    "ca_redemption_value": "0.60",
    "co_retail_delivery_fee": "0.00",
    "me_bottle_deposit": "0.00",
    "tax": "35.64",
    "shipping": "25.00",
    "shipping_insurance": "0.00",
    "tip": "0.00",
    "total": "492.64"
}

ClubMembers

Resources related to ClubMembers.

PUT /clubMembers/{id}/cancel cancel

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
NameTypeRequiredDescriptionExample
id number Required Club Member Id
cancellation_reason string Optional Cancellation reason (Personal | Health | Too much wine | Financial | Moving | No longer interested | Other)
Examples
Request
PUT/clubMembers/{id}/cancel
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "cancellation_reason": "Moving"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "customer_id": "100216",
    "club_id": "12",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "1",
    "cancellation_date": "2026-02-10 11:04:22",
    "cancellation_reason": "Moving",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
}
POST /clubMembers create

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
NameTypeRequiredDescriptionExample
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)
Examples
Request
POST/clubMembers
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "customer_id": "100216",
    "club_id": "12",
    "method_id": "6",
    "address_id": "44120",
    "payment_id": "88231",
    "signup_type": "Web",
    "is_gift": "No",
    "email_template": "",
    "delivery_preference": "shipping",
    "method_id_shipping": "6"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "customer_id": "100216",
    "club_id": "12",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "Ready",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "0",
    "cancellation_date": "0000-00-00 00:00:00",
    "cancellation_reason": "",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
}
DELETE /clubMembers/{id} delete

Permanently deletes a membership by id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Member Id
Examples
Request
DELETE/clubMembers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /clubMembers/{id} get

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Member Id
Examples
Request
GET/clubMembers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "customer_id": "100216",
    "club_id": "12",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "Ready",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "0",
    "cancellation_date": "0000-00-00 00:00:00",
    "cancellation_reason": "",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
}
GET /clubMembers getAll

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.

Examples
Request
GET/clubMembers
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "5581",
        "customer_id": "100216",
        "club_id": "12",
        "payment_id": "88231",
        "address_id": "44120",
        "method_id": "6",
        "cart_session": "club-12-5581",
        "exclude_until": "",
        "status": "Ready",
        "authorization": "",
        "amount": "210.00",
        "total": "210.00",
        "error": "",
        "created": "2021-06-14 10:22:41",
        "last_update": "2026-02-16 15:17:00",
        "canceled": "0",
        "cancellation_date": "0000-00-00 00:00:00",
        "cancellation_reason": "",
        "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
    }
]
GET /clubMembers/canceled getCanceled

Returns all cancelled memberships (canceled = 1), each carrying its cancellation_date and cancellation_reason.

Examples
Request
GET/clubMembers/canceled
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "5581",
        "customer_id": "100216",
        "club_id": "12",
        "payment_id": "88231",
        "address_id": "44120",
        "method_id": "6",
        "cart_session": "club-12-5581",
        "exclude_until": "",
        "status": "",
        "authorization": "",
        "amount": "210.00",
        "total": "210.00",
        "error": "",
        "created": "2021-06-14 10:22:41",
        "last_update": "2026-02-16 15:17:00",
        "canceled": "1",
        "cancellation_date": "2026-02-10 11:04:22",
        "cancellation_reason": "Moving",
        "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
    }
]
GET /clubMembers/{id}/canceled getCanceledByCustomer

Returns a customer's cancelled memberships ({id} is the customer id), each with its cancellation_date and cancellation_reason.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/clubMembers/{id}/canceled
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "5581",
        "customer_id": "100216",
        "club_id": "12",
        "payment_id": "88231",
        "address_id": "44120",
        "method_id": "6",
        "cart_session": "club-12-5581",
        "exclude_until": "",
        "status": "",
        "authorization": "",
        "amount": "210.00",
        "total": "210.00",
        "error": "",
        "created": "2021-06-14 10:22:41",
        "last_update": "2026-02-16 15:17:00",
        "canceled": "1",
        "cancellation_date": "2026-02-10 11:04:22",
        "cancellation_reason": "Moving",
        "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
    }
]
DELETE /clubMembers/{id}/cancel uncancel

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Member Id
Examples
Request
DELETE/clubMembers/{id}/cancel
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "customer_id": "100216",
    "club_id": "12",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "Ready",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "0",
    "cancellation_date": "0000-00-00 00:00:00",
    "cancellation_reason": "",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
}
PUT /clubMembers/{id} update

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
NameTypeRequiredDescriptionExample
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)
Examples
Request
PUT/clubMembers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "club_id": "12",
    "method_id": "9",
    "address_id": "44120",
    "payment_id": "88231",
    "admin_comments": "Prefers even-numbered allocations.",
    "delivery_preference": "pickup",
    "method_id_pickup": "9"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "customer_id": "100216",
    "club_id": "12",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "Ready",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "0",
    "cancellation_date": "0000-00-00 00:00:00",
    "cancellation_reason": "",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}"
}

Clubs

Resources related to Clubs.

POST /clubs create

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
NameTypeRequiredDescriptionExample
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
Examples
Request
POST/clubs
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "name": "Cellar Club",
    "status": "Inactive",
    "description": "<p>Our flagship allocation club.</p>",
    "club_info_1": "<p>Three curated shipments per year.</p>",
    "club_info_2": "$150 - $300 per shipment",
    "club_confirmation_message": "<p>Welcome!</p>",
    "discount": "10",
    "free_shipping": "1",
    "signup_groups": "4,7"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "12",
    "name": "Cellar Club",
    "status": "Active",
    "description": "<p>Our flagship allocation club.</p>",
    "club_info_1": "<p>Three curated shipments per year.</p>",
    "club_info_2": "$150 - $300 per shipment",
    "club_confirmation_message": "<p>Welcome to the Cellar Club!</p>",
    "discount": "10",
    "free_shipping": "1",
    "signup_groups": "4,7",
    "member_count": "342",
    "order_status": "",
    "last_update": "2026-02-16 15:17:00",
    "created": "2019-04-02 09:12:33"
}
POST /clubs/{id}/order createOrder

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
subtotal number Optional Batch order subtotal
shipping_method number Optional Shipping method id
free_shipping boolean Optional Free shipping (1|0)
requested_ship_date string Optional Requested ship date (Y-m-d)
ship_status string Optional Initial ship status
discount number Optional Order-level discount
items array Required Batch items: {sku,name,price,quantity,min_purchase,max_purchase,tax_exempt,shipping_included,bottle_size}
Examples
Request
POST/clubs/{id}/order
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "subtotal": "180.00",
    "shipping_method": "6",
    "free_shipping": "0",
    "requested_ship_date": "2026-03-02",
    "ship_status": "Not Shipped",
    "discount": "0.00",
    "items": [
        {
            "sku": "2021-PN-750",
            "name": "2021 Estate Pinot Noir",
            "price": "60.00",
            "quantity": "3",
            "min_purchase": "3",
            "max_purchase": "6",
            "tax_exempt": "No",
            "shipping_included": "0",
            "bottle_size": "750mL"
        }
    ]
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "club_id": "12",
    "order_status": "1",
    "carts_created": "342",
    "requested_ship_date": "2026-03-02"
}
DELETE /clubs/{id} delete

Permanently deletes a club by id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
Examples
Request
DELETE/clubs/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
DELETE /clubs/{id}/order deleteOrder

Discards the club's in-process batch order, clearing the saved order_data and the members' reserved carts. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
Examples
Request
DELETE/clubs/{id}/order
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /clubs/{id} get

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).

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
Examples
Request
GET/clubs/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "12",
    "name": "Cellar Club",
    "status": "Active",
    "description": "<p>Our flagship allocation club.</p>",
    "club_info_1": "<p>Three curated shipments per year.</p>",
    "club_info_2": "$150 - $300 per shipment",
    "club_confirmation_message": "<p>Welcome to the Cellar Club!</p>",
    "discount": "10",
    "free_shipping": "1",
    "signup_groups": "4,7",
    "member_count": "342",
    "order_status": "",
    "last_update": "2026-02-16 15:17:00",
    "created": "2019-04-02 09:12:33"
}
GET /clubs getAll

Returns all club definitions as an array, each with its derived member_count and current order_status.

Examples
Request
GET/clubs
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "12",
        "name": "Cellar Club",
        "status": "Active",
        "description": "<p>Our flagship allocation club.</p>",
        "club_info_1": "<p>Three curated shipments per year.</p>",
        "club_info_2": "$150 - $300 per shipment",
        "club_confirmation_message": "<p>Welcome to the Cellar Club!</p>",
        "discount": "10",
        "free_shipping": "1",
        "signup_groups": "4,7",
        "member_count": "342",
        "order_status": "",
        "last_update": "2026-02-16 15:17:00",
        "created": "2019-04-02 09:12:33"
    }
]
GET /clubs/{id}/members/{member_id} getMember

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
member_id number Required Club Member Id
Examples
Request
GET/clubs/{id}/members/{member_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "5581",
    "club_id": "12",
    "customer_id": "100216",
    "payment_id": "88231",
    "address_id": "44120",
    "method_id": "6",
    "cart_session": "club-12-5581",
    "exclude_until": "",
    "status": "Ready",
    "authorization": "",
    "amount": "210.00",
    "total": "210.00",
    "error": "",
    "created": "2021-06-14 10:22:41",
    "last_update": "2026-02-16 15:17:00",
    "canceled": "0",
    "cancelation_date": "0000-00-00 00:00:00",
    "cancellation_reason": "",
    "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}",
    "customer": {
        "id": "100216",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "phone": "7075551234"
    },
    "address": {
        "id": "44120",
        "first_name": "Jane",
        "last_name": "Doe",
        "address": "100 Vine St",
        "city": "Napa",
        "state": "CA",
        "zip": "94558",
        "country": "US"
    },
    "payment": {
        "id": "88231",
        "credit_type": "Visa",
        "credit_number": "4242",
        "credit_expires_month": "08",
        "credit_expires_year": "2027"
    },
    "groups": "Allocation Tier A"
}
GET /clubs/{id}/members/count getMemberCount

Returns the club's member count as a numeric string.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
Examples
Request
GET/clubs/{id}/members/count
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
"342"
GET /clubs/{id}/members getMembers

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
Examples
Request
GET/clubs/{id}/members
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "5581",
        "club_id": "12",
        "customer_id": "100216",
        "payment_id": "88231",
        "address_id": "44120",
        "method_id": "6",
        "cart_session": "club-12-5581",
        "exclude_until": "",
        "status": "Ready",
        "authorization": "",
        "amount": "210.00",
        "total": "210.00",
        "error": "",
        "created": "2021-06-14 10:22:41",
        "last_update": "2026-02-16 15:17:00",
        "canceled": "0",
        "cancelation_date": "0000-00-00 00:00:00",
        "cancellation_reason": "",
        "data": "{\"is_gift\":\"No\",\"signup_type\":\"Web\",\"sales_person\":\"\",\"referral\":\"\",\"delivery_preference\":\"shipping\",\"method_id_shipping\":\"6\",\"method_id_pickup\":\"\",\"admin_comments\":\"\",\"notify_recipient\":\"0\",\"special_instructions\":\"0\",\"do_not_combine\":\"0\",\"override_shipping\":false}",
        "customer": {
            "id": "100216",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane@example.com",
            "phone": "7075551234"
        },
        "address": {
            "id": "44120",
            "first_name": "Jane",
            "last_name": "Doe",
            "address": "100 Vine St",
            "city": "Napa",
            "state": "CA",
            "zip": "94558",
            "country": "US"
        },
        "payment": {
            "id": "88231",
            "credit_type": "Visa",
            "credit_number": "4242",
            "credit_expires_month": "08",
            "credit_expires_year": "2027"
        },
        "groups": "Allocation Tier A"
    }
]
DELETE /clubs/{id}/members/{member_id} removeMember

Removes membership {member_id} from club {id}. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
member_id number Required Club Member Id
Examples
Request
DELETE/clubs/{id}/members/{member_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /clubs/{id}/sort/{position} reorder

Sets the club's display sort position. Returns true. The position is write-only - it has no direct read on the club object.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
position number Required New sort position
Examples
Request
PUT/clubs/{id}/sort/{position}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /clubs/{id} update

Updates a club definition using the same field set as create, with signup_groups imploded to a CSV. Returns the updated club.

Parameters
NameTypeRequiredDescriptionExample
id number Required Club Id
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
Examples
Request
PUT/clubs/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "name": "Cellar Club",
    "status": "Active",
    "discount": "15",
    "free_shipping": "1",
    "signup_groups": "4,7"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "12",
    "name": "Cellar Club",
    "status": "Active",
    "description": "<p>Our flagship allocation club.</p>",
    "club_info_1": "<p>Three curated shipments per year.</p>",
    "club_info_2": "$150 - $300 per shipment",
    "club_confirmation_message": "<p>Welcome to the Cellar Club!</p>",
    "discount": "10",
    "free_shipping": "1",
    "signup_groups": "4,7",
    "member_count": "342",
    "order_status": "",
    "last_update": "2026-02-16 15:17:00",
    "created": "2019-04-02 09:12:33"
}

Customers

Resources related to Customers.

POST /customers Create Customer

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).

Parameters
NameTypeRequiredDescriptionExample
email string Required Customer Email Address
first_name string Required Customer First Name
last_name string Required Customer Last Name
password string Required Customer Password
Examples
Request
POST/customers
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "first_name": "John",
    "last_name": "Doe",
    "email": "example@commercebyfigure.com",
    "password": "XXXXXXXXX"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "first_name": "John",
    "last_name": "Doe",
    "email": "example@commercebyfigure.com",
    "status": "Active",
    "state": "",
    "order_count": "0",
    "order_total": "0.00",
    "last_order": "0000-00-00 00:00:00",
    "last_order_total": "0.00",
    "last_update": "2018-04-18 16:14:00",
    "created": "2018-04-18 16:14:00",
    "signup_email_last_sent": "2018-04-18 16:14:00"
}
DELETE /customers/{id} Delete Customer

Permanently deletes a customer. Blocked if the customer has any order history; returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
DELETE/customers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
POST /customers/filter Filter Customers

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.

Examples
Request
POST/customers/filter
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
[
    {
        "type": "range",
        "key": "created",
        "from": 1522540800,
        "to": 1524097161
    },
    {
        "type": "term",
        "key": "customer_source",
        "value": "Web"
    }
]
Response
Headers · 200
Content-Type: application/json
Body
{
    "42": {
        "id": "42",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@commercebyfigure.com",
        "status": "Active",
        "state": "CA",
        "customer_source": "Web",
        "order_count": "0",
        "order_total": "0.00",
        "last_order": "0000-00-00 00:00:00",
        "last_order_total": "0.00",
        "last_update": "2018-04-18 16:35:48",
        "created": "2018-04-18 16:14:00",
        "signup_email_last_sent": "2018-04-18 16:14:00"
    }
}
GET /customers/{id} Get Customer

Retrieves a single customer by id, including derived purchase-history and lifecycle fields.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/customers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "first_name": "John",
    "last_name": "Doe",
    "email": "example@commercebyfigure.com",
    "status": "Active",
    "state": "CA",
    "order_count": "0",
    "order_total": "0.00",
    "last_order": "0000-00-00 00:00:00",
    "last_order_total": "0.00",
    "last_update": "2018-04-18 16:14:00",
    "created": "2018-04-18 16:14:00",
    "signup_email_last_sent": "2018-04-18 16:14:00"
}
GET /customers/{id}/clubs Get Customer Clubs

Returns the club memberships associated with the customer. Empty array when the customer belongs to no clubs.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/customers/{id}/clubs
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[]
GET /customers/{id}/transactions Get Customer Transactions

Returns the customer's payment transaction rows (debits, refunds, and chargebacks) across all of their orders.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/customers/{id}/transactions
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[]
GET /customers/search/{query} Search Customers

Full-text search across customers (name, email, and related fields), returning matches keyed by id. For structured criteria use the filter endpoint instead.

Parameters
NameTypeRequiredDescriptionExample
query string Required Customer Search Query String
Examples
Request
GET/customers/search/{query}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "42": {
        "id": "42",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@commercebyfigure.com",
        "status": "Active",
        "state": "CA",
        "customer_source": "Web",
        "order_count": "0",
        "order_total": "0.00",
        "last_order": "0000-00-00 00:00:00",
        "last_order_total": "0.00",
        "last_update": "2018-04-18 16:35:48",
        "created": "2018-04-18 16:14:00",
        "signup_email_last_sent": "2018-04-18 16:14:00"
    }
}
PUT /customers/{id} Update Customer

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
PUT/customers/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "state": "CA"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "first_name": "John",
    "last_name": "Doe",
    "email": "example@commercebyfigure.com",
    "status": "Active",
    "state": "CA",
    "order_count": "0",
    "order_total": "0.00",
    "last_order": "0000-00-00 00:00:00",
    "last_order_total": "0.00",
    "last_update": "2018-04-18 16:35:48",
    "created": "2018-04-18 16:14:00",
    "signup_email_last_sent": "2018-04-18 16:14:00"
}
PUT /customers/{id}/password Update Customer Password

Sets the customer's login password to the supplied value. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
PUT/customers/{id}/password
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "password": "XXXXXXXXX"
}
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /customers/{id}/groups/{group_id} Add Customer To Group

Adds the customer to the given group. Returns true; idempotent if the customer is already a member.

Parameters
NameTypeRequiredDescriptionExample
group_id number Required Group Id
id number Required Customer Id
Examples
Request
PUT/customers/{id}/groups/{group_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
DELETE /customers/{id}/groups Clear All Customer Groups

Removes the customer from every group they belong to. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
DELETE/customers/{id}/groups
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /customers/{id}/groups Get Customer Groups

Returns the groups the customer belongs to, keyed by group id, each with its discount, free-shipping, and checkout-minimum settings.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/customers/{id}/groups
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "1": {
        "id": "1",
        "name": "Mailing List",
        "discount": "0",
        "free_shipping": "0",
        "checkout_cart_min": "0"
    },
    "2": {
        "id": "2",
        "name": "Customer Group I",
        "discount": "0",
        "free_shipping": "0",
        "checkout_cart_min": "0"
    }
}
DELETE /customers/{id}/groups/{group_id} Remove Customer From Group

Removes the customer from a single group. Returns true.

Parameters
NameTypeRequiredDescriptionExample
group_id number Required Group Id
id number Required Customer Id
Examples
Request
DELETE/customers/{id}/groups/{group_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
POST /customers/{id}/notes Add Customer Note

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
POST/customers/{id}/notes
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "message": "John would like to ship FedEx if possible.",
    "user_id": 1,
    "user_name": "Jane Doe",
    "type": "Admin"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": 246,
    "customer_id": "42",
    "message": "John would like to ship FedEx if possible.",
    "user_id": 1,
    "user_name": "Jane Doe",
    "type": "Admin"
}
GET /customers/{id}/notes/{type} Get Customer Notes

Returns the customer's notes of the given type (Log for the activity log, Admin for the editable notes panel), newest first.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
type string Required Note Type
Examples
Request
GET/customers/{id}/notes/{type}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "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 /customers/{id}/tags/{tag} Add Tag to Customer

Attaches a tag to the customer. Tags are stored uppercased; returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
tag string Required Tag
Examples
Request
PUT/customers/{id}/tags/{tag}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
DELETE /customers/{id}/tags Clear All Tags from Customer

Removes all tags from the customer. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
DELETE/customers/{id}/tags
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /customers/{id}/tags Get Customer Tags

Returns the customer's tags as an array of strings.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
Examples
Request
GET/customers/{id}/tags
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    "VIPCustomer",
    "FedExOnly"
]
DELETE /customers/{id}/tags/{tag} Remove Tag from Customer

Removes a single tag from the customer. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Customer Id
tag string Required Tag
Examples
Request
DELETE/customers/{id}/tags/{tag}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true

Groups

Resources related to Groups.

POST /groups Create Group

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).

Parameters
NameTypeRequiredDescriptionExample
description string Optional Description of Group
name string Required Group Title
status string Optional Group Status
Examples
Request
POST/groups
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "name": "Customer Group I",
    "status": "Active",
    "description": "New Customer Group."
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "2",
    "name": "Customer Group I",
    "status": "Active",
    "sort": "0",
    "allocation_message": "",
    "allocation_start": "0000-00-00 00:00:00",
    "checkout_cart_min": "0",
    "allocation_end": "0000-00-00 00:00:00",
    "discount": "0",
    "free_shipping": "0",
    "description": "New Customer Group."
}
DELETE /groups/{id} Delete Group

Permanently deletes a group by id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
Examples
Request
DELETE/groups/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /groups Get All Groups

Returns all groups (including archived ones), keyed by id. Use the non-archived variants to hide archived groups in pickers.

Examples
Request
GET/groups
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "2": {
        "id": "2",
        "name": "Customer Group I",
        "status": "Active",
        "sort": "0",
        "allocation_message": "",
        "allocation_start": "0000-00-00 00:00:00",
        "checkout_cart_min": "0",
        "allocation_end": "0000-00-00 00:00:00",
        "discount": "0",
        "free_shipping": "0",
        "description": "Updated Customer Group"
    },
    "1": {
        "id": "1",
        "name": "Mailing List",
        "status": "Active",
        "sort": "0",
        "allocation_message": "",
        "allocation_start": "0000-00-00 00:00:00",
        "checkout_cart_min": "0",
        "allocation_end": "0000-00-00 00:00:00",
        "discount": "0",
        "free_shipping": "0"
    }
}
GET /groups/{id}/customers Get Customers In Group

Returns the customers who are members of the given group, hydrated as customer objects keyed by id.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
Examples
Request
GET/groups/{id}/customers
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "42": {
        "id": "42",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@commercebyfigure.com",
        "status": "Active",
        "state": "CA",
        "order_count": "0",
        "order_total": "0.00",
        "last_order": "0000-00-00 00:00:00",
        "last_order_total": "0.00",
        "last_update": "2018-04-18 16:35:48",
        "created": "2018-04-18 16:14:00",
        "signup_email_last_sent": "2018-04-18 16:14:00"
    }
}
GET /groups/{id} Get Group

Retrieves a single group by id, including its discount, free-shipping, exclusive-access, and allocation-window settings.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
Examples
Request
GET/groups/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "2",
    "name": "Customer Group I",
    "status": "Active",
    "sort": "0",
    "allocation_message": "",
    "allocation_start": "0000-00-00 00:00:00",
    "checkout_cart_min": "0",
    "allocation_end": "0000-00-00 00:00:00",
    "discount": "0",
    "free_shipping": "0",
    "description": "New Customer Group."
}
PUT /groups/{id} Update Group

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
Examples
Request
PUT/groups/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "description": "Updated Customer Group"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "2",
    "name": "Customer Group I",
    "status": "Active",
    "sort": "0",
    "allocation_message": "",
    "allocation_start": "0000-00-00 00:00:00",
    "checkout_cart_min": "0",
    "allocation_end": "0000-00-00 00:00:00",
    "discount": "0",
    "free_shipping": "0",
    "description": "Updated Customer Group"
}
GET /groups/{id}/allocation Get Group Allocation

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
Examples
Request
GET/groups/{id}/allocation
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "CAB19": {
        "sku": "CAB19",
        "min_quantity": "1",
        "quantity": "6",
        "min_wish": "0",
        "max_wish": "12",
        "increment_override": "1",
        "sort": "0",
        "name": "2019 Estate Cabernet",
        "inventory": "340",
        "increment": "1",
        "bottle_size": "750ml"
    }
}
POST /groups/{id}/allocation Add Group Allocation Item

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
sku string Required Product SKU
increment_override number Optional Override the product's purchase increment
min_quantity number Optional Min Purchase per customer
quantity number Optional Max Purchase per customer (NOT inventory)
min_wish number Optional Minimum wishlist quantity
max_wish number Optional Maximum wishlist quantity
Examples
Request
POST/groups/{id}/allocation
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "sku": "CAB19",
    "increment_override": "1",
    "min_quantity": "1",
    "quantity": "6",
    "min_wish": "0",
    "max_wish": "12"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "sku": "CAB19",
    "min_quantity": "1",
    "quantity": "6",
    "min_wish": "0",
    "max_wish": "12",
    "increment_override": "1",
    "sort": "0",
    "name": "2019 Estate Cabernet",
    "inventory": "340",
    "increment": "1",
    "bottle_size": "750ml"
}
DELETE /groups/{id}/allocation/{sku} Remove Group Allocation Item

Removes a single allocation product from the group by SKU.

Parameters
NameTypeRequiredDescriptionExample
id number Required Group Id
sku string Required Product SKU to remove
Examples
Request
DELETE/groups/{id}/allocation/{sku}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "success": true
}

Orders

Resources related to Orders.

DELETE /orders/{id} Cancel Order

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
DELETE/orders/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
POST /orders/filter Filter Orders

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.

Examples
Request
POST/orders/filter
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
[
    {
        "type": "range",
        "key": "datestamp",
        "from": 1522540800,
        "to": 1524097161
    },
    {
        "type": "term",
        "key": "payment_status",
        "value": "Paid"
    },
    {
        "type": "terms",
        "key": "ship_status",
        "value": [
            "Shipped",
            "Picked Up",
            "Completed"
        ]
    }
]
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "datestamp": "2018-03-23 16:24:15",
    "last_update": "2018-03-23 16:24:15",
    "status": "",
    "subtotal": "45.00",
    "tax": "3.15",
    "shipping": "20.00",
    "discount": "9.00",
    "credits": "0.00",
    "refund": "0.00",
    "total": "59.15",
    "customer_id": "1",
    "address": "",
    "address_2": "",
    "address_id": "3979",
    "birthday": "1982-11-1",
    "city": "",
    "company": "",
    "credit_id": "19",
    "credit_number": "4242",
    "credit_type": "Visa",
    "customer_credits": "0.00",
    "discount_customer": "0.2",
    "email": "example@commercebyfigure.com",
    "first_name": "John",
    "gift_message": "",
    "instructions": "",
    "item_count": "1",
    "last_name": "Doe",
    "order_id": "42",
    "order_type": "Web",
    "payment_status": "Paid",
    "phone": "707-287-6262",
    "salutation": "Mr.",
    "shipping_address": "770 3rd St E",
    "shipping_address_2": "",
    "shipping_city": "Sonoma",
    "shipping_company": "",
    "shipping_first_name": "John",
    "shipping_id": "3979",
    "shipping_last_name": "Doe",
    "shipping_method": "11",
    "shipping_method_carrier": "FedEx",
    "shipping_method_code": "FDXGND",
    "shipping_method_name": "Ground",
    "shipping_phone": "707-287-6262",
    "shipping_state": "CA",
    "shipping_title": "Shipping Address",
    "shipping_zip": "95476",
    "ship_status": "Shipped",
    "state": "",
    "tax_rate": "8.75",
    "transaction_id": "36",
    "zip": "",
    "products": [
        {
            "id": "42",
            "sku": "H",
            "name": "2017 Pinot Meunier",
            "type": "",
            "bottle_size": "750mL",
            "retail_price": "0.00",
            "discount": "0.00",
            "discount_type": "",
            "price": "45",
            "quantity": "1",
            "status": "",
            "description": "2017 Pinot Meunier ",
            "image": "",
            "stock_status": "",
            "shipped": "0",
            "created": "2018-03-23 16:24:18"
        }
    ]
}
GET /orders/{id} Get Order

Retrieves a single order by id, including its monetary totals, addresses, status fields, and line items.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
GET/orders/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "datestamp": "2018-03-23 16:24:15",
    "last_update": "2018-03-23 16:24:15",
    "status": "",
    "subtotal": "45.00",
    "tax": "3.15",
    "shipping": "20.00",
    "discount": "9.00",
    "credits": "0.00",
    "refund": "0.00",
    "total": "59.15",
    "customer_id": "1",
    "address": "",
    "address_2": "",
    "address_id": "3979",
    "birthday": "1982-11-1",
    "city": "",
    "company": "",
    "credit_id": "19",
    "credit_number": "4242",
    "credit_type": "Visa",
    "customer_credits": "0.00",
    "discount_customer": "0.2",
    "email": "example@commercebyfigure.com",
    "first_name": "John",
    "gift_message": "",
    "instructions": "",
    "item_count": "1",
    "last_name": "Doe",
    "order_id": "42",
    "order_type": "Web",
    "payment_status": "Paid",
    "phone": "707-287-6262",
    "salutation": "Mr.",
    "shipping_address": "770 3rd St E",
    "shipping_address_2": "",
    "shipping_city": "Sonoma",
    "shipping_company": "",
    "shipping_first_name": "John",
    "shipping_id": "3979",
    "shipping_last_name": "Doe",
    "shipping_method": "11",
    "shipping_method_carrier": "FedEx",
    "shipping_method_code": "FDXGND",
    "shipping_method_name": "Ground",
    "shipping_phone": "707-287-6262",
    "shipping_state": "CA",
    "shipping_title": "Shipping Address",
    "shipping_zip": "95476",
    "ship_status": "Not Shipped",
    "state": "",
    "tax_rate": "8.75",
    "transaction_id": "36",
    "zip": "",
    "products": [
        {
            "id": "42",
            "sku": "H",
            "name": "2017 Pinot Meunier",
            "type": "",
            "bottle_size": "750mL",
            "retail_price": "0.00",
            "discount": "0.00",
            "discount_type": "",
            "price": "45",
            "quantity": "1",
            "status": "",
            "description": "2017 Pinot Meunier ",
            "image": "",
            "stock_status": "",
            "shipped": "0",
            "created": "2018-03-23 16:24:18"
        }
    ]
}
GET /orders/search/{query} Search Orders

Full-text search across orders. For structured criteria (status, date, SKU, tags) use the filter endpoint instead.

Parameters
NameTypeRequiredDescriptionExample
query string Required Order Search Query String
Examples
Request
GET/orders/search/{query}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "42",
    "datestamp": "2018-03-23 16:24:15",
    "last_update": "2018-03-23 16:24:15",
    "status": "",
    "subtotal": "45.00",
    "tax": "3.15",
    "shipping": "20.00",
    "discount": "9.00",
    "credits": "0.00",
    "refund": "0.00",
    "total": "59.15",
    "customer_id": "1",
    "address": "",
    "address_2": "",
    "address_id": "3979",
    "birthday": "1982-11-1",
    "city": "",
    "company": "",
    "credit_id": "19",
    "credit_number": "4242",
    "credit_type": "Visa",
    "customer_credits": "0.00",
    "discount_customer": "0.2",
    "email": "example@commercebyfigure.com",
    "first_name": "John",
    "gift_message": "",
    "instructions": "",
    "item_count": "1",
    "last_name": "Doe",
    "order_id": "42",
    "order_type": "Web",
    "payment_status": "Paid",
    "phone": "707-287-6262",
    "salutation": "Mr.",
    "shipping_address": "770 3rd St E",
    "shipping_address_2": "",
    "shipping_city": "Sonoma",
    "shipping_company": "",
    "shipping_first_name": "John",
    "shipping_id": "3979",
    "shipping_last_name": "Doe",
    "shipping_method": "11",
    "shipping_method_carrier": "FedEx",
    "shipping_method_code": "FDXGND",
    "shipping_method_name": "Ground",
    "shipping_phone": "707-287-6262",
    "shipping_state": "CA",
    "shipping_title": "Shipping Address",
    "shipping_zip": "95476",
    "ship_status": "Shipped",
    "state": "",
    "tax_rate": "8.75",
    "transaction_id": "36",
    "zip": "",
    "products": [
        {
            "id": "42",
            "sku": "H",
            "name": "2017 Pinot Meunier",
            "type": "",
            "bottle_size": "750mL",
            "retail_price": "0.00",
            "discount": "0.00",
            "discount_type": "",
            "price": "45",
            "quantity": "1",
            "status": "",
            "description": "2017 Pinot Meunier ",
            "image": "",
            "stock_status": "",
            "shipped": "0",
            "created": "2018-03-23 16:24:18"
        }
    ]
}
PUT /pos/orders/{id} Update Order

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.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
PUT/pos/orders/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "ship_status": "Picked Up",
    "actual_ship_date": "2020-04-04 10:00:00",
    "shipping_first_name": "Tyson",
    "shipping_last_name": "Caly",
    "shipping_address": "100 Main St.",
    "shipping_address_2": "Ste 2",
    "shipping_city": "Napa",
    "shipping_state": "CA",
    "shipping_zip": "94559"
}
Response
Headers · 200
Content-Type: application/json
Body
true
POST /orders/{id}/notes Add Note

Adds a note to the order. type selects Log (activity log) or Admin (notes panel, the default); category defaults to General. Returns the created note.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
POST/orders/{id}/notes
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "message": "John would like to ship FedEx if possible.",
    "user_id": 1,
    "user_name": "Jane Doe",
    "type": "Admin"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": 197,
    "customer_id": "42",
    "message": "John would like to ship FedEx if possible.",
    "user_id": 1,
    "user_name": "Jane Doe",
    "type": "Admin"
}
GET /orders/{id}/notes/{type} Get Notes

Returns the order's notes of the given type (Log for the activity log, Admin for the editable notes panel), newest first.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
type string Required Note Type
Examples
Request
GET/orders/{id}/notes/{type}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "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}/packages Add Packages

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.

Parameters
NameTypeRequiredDescriptionExample
Carrier string Required Shipment Carrier
DateShipped string Optional Date Package was Shipped
ShipMethod string Required Shipping Method
ShipToName string Optional Recipient Name
TotalCharges number Optional Shipping Cost
TrackingNumber string Required Tracking Number
Weight number Optional Package Weight
id number Required Order Id
Examples
Request
PUT/orders/{id}/packages
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
[
    {
        "TrackingNumber": "1z078b0v1475364917",
        "Carrier": "UPS",
        "ShipMethod": "UP2",
        "DateShipped": "2022-05-22",
        "ShipToName": "John Smith",
        "TotalCharges": 14.85,
        "Weight": 3.5
    },
    {
        "TrackingNumber": "538134318386",
        "Carrier": "FedEx",
        "ShipMethod": "FXG",
        "DateShipped": "2022-05-24",
        "ShipToName": "John Smith",
        "TotalCharges": 18.4,
        "Weight": 6
    }
]
Response
Headers · 200
Content-Type: application/json
Body
true
DELETE /orders/{id}/packages Clear Packages

Removes all tracking packages from the order. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
DELETE/orders/{id}/packages
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /orders/{id}/packages Get Packages

Returns the order's tracking packages, each with its tracking number, carrier, ship method, and ship date. Empty array when none exist.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
GET/orders/{id}/packages
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[]
DELETE /orders/{id}/packages/{tracking_number} Remove Package

Removes a single package from the order, keyed by its tracking number. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
tracking_number string Required Package Tracking Number
Examples
Request
DELETE/orders/{id}/packages/{tracking_number}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /orders/{id}/tags/{tag} Add Tag

Attaches a tag to the order. Tags are stored uppercased; returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
tag string Required Tag
Examples
Request
PUT/orders/{id}/tags/{tag}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
DELETE /orders/{id}/tags Clear Tags

Removes all tags from the order. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
DELETE/orders/{id}/tags
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /orders/{id}/tags Get Tags

Returns the order's tags as an array of strings.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
Examples
Request
GET/orders/{id}/tags
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    "RushDevliery",
    "FedExOnly"
]
DELETE /orders/{id}/tags/{tag} Remove Tag

Removes a single tag from the order. Returns true.

Parameters
NameTypeRequiredDescriptionExample
id number Required Order Id
tag string Required Tag
Examples
Request
DELETE/orders/{id}/tags/{tag}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /orders/{limit}/{page} Get All Orders

Paginated list of all orders, most recent first. Pass the page size and page number as path segments.

Parameters
NameTypeRequiredDescriptionExample
limit number Required Page size (rows per page)
page number Required Page number (1-based)
Examples
Request
GET/orders/{limit}/{page}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "order_id": "S1042",
        "code": "S1042",
        "status": "Complete",
        "ship_status": "Shipped",
        "payment_status": "Paid",
        "order_type": "Web",
        "created": "2026-02-16 15:17:00",
        "customer_id": "8842",
        "first_name": "Dana",
        "last_name": "Whitfield",
        "email": "dana@example.com",
        "total": "147.90",
        "item_count": "2"
    }
]
DELETE /orders/saved/{session} Delete Saved Order

Discard a saved/pending order cart session by its session id, releasing any reserved cart state.

Parameters
NameTypeRequiredDescriptionExample
session string Required Saved-order cart session id
Examples
Request
DELETE/orders/saved/{session}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "success": true
}
POST /orders/{id} Update Order (Standard)

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
NameTypeRequiredDescriptionExample
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)
compliance_error string Optional Compliance error text
sc_tax_type string Optional ShipCompliant tax type (onsite/offsite)
ship_compliant_split_ids string Optional CSV of split order ids
editable_notes string Optional Editable notes panel content
fraudulent string Optional Fraudulent tag
wishlist_session_id string Optional Associated wishlist session id
Examples
Request
POST/orders/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "status": "Complete",
    "ship_status": "Shipped",
    "actual_ship_date": "2026-02-17",
    "compliance_status": "Compliant",
    "editable_notes": "Left with neighbor per customer request."
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "order_id": "S1042",
    "status": "Complete",
    "ship_status": "Shipped",
    "actual_ship_date": "2026-02-17",
    "compliance_status": "Compliant",
    "editable_notes": "Left with neighbor per customer request.",
    "total": "147.90",
    "item_count": "2",
    "last_saved": "2026-02-17 09:14:00"
}

Payment

Resources related to Payment.

POST /payment Create Payment Method

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.

Parameters
NameTypeRequiredDescriptionExample
address string Required Street Address
address_2 string Optional Unit Number
card_token string Required Stripe Credit Card Token
card_type string Required Credit Card Brand ie: Visa, American Express, etc
city string Required City
credit_expires_month string Required Expires Month ie: 06
credit_expires_year string Required Expires Year ie: 2016
credit_number string Required Last 4 Digits of Credit Card Number
customer_id number Required Customer Id
first_name string Required Customer First Name
last_name string Required Customer Last Name
phone string Optional Customer Phone Number
state string Required State
zip string Required Zip Code
Examples
Request
POST/payment
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "first_name": "Jane",
    "last_name": "Doe",
    "card_token": "XXXXXXXXX",
    "credit_type": "Visa",
    "credit_number": "1111",
    "credit_expires_month": "6",
    "credit_expires_year": "2026",
    "birthday": "1980-01-01",
    "company": "Figure Commerce",
    "phone": "7075558520",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "22",
    "fingerprint": "",
    "credit_type": "Visa",
    "credit_number": "1111",
    "credit_expires_month": "6",
    "credit_expires_year": "2026",
    "profile_id": "0",
    "payment_profile_id": "0",
    "first_name": "Jane",
    "birthday": "",
    "phone": "",
    "company": "",
    "last_name": "Doe",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42",
    "default": "1",
    "created": "2018-03-05 22:03:01",
    "last_update": "0000-00-00 00:00:00"
}
DELETE /payment/{id} Delete Payment Method

Deletes the stored payment method with the given id. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
id number Required Payment Method Id
Examples
Request
DELETE/payment/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
GET /payment Get All Payment Menthods

Returns all stored payment methods, keyed by id.

Examples
Request
GET/payment
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "22": {
        "id": "22",
        "fingerprint": "",
        "credit_type": "Visa",
        "credit_number": "1111",
        "credit_expires_month": "6",
        "credit_expires_year": "2026",
        "profile_id": "0",
        "payment_profile_id": "0",
        "first_name": "Jane",
        "birthday": "",
        "phone": "",
        "company": "",
        "last_name": "Doe",
        "address": "100 Main St",
        "address_2": "",
        "city": "Napa",
        "state": "CA",
        "zip": "94559",
        "country": "US",
        "customer_id": "42",
        "default": "1",
        "created": "2018-03-05 22:03:01",
        "last_update": "0000-00-00 00:00:00"
    }
}
GET /payment/customer/{customer_id}/default Get Default Customer Payment Method

Returns the customer's default stored payment method.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
Examples
Request
GET/payment/customer/{customer_id}/default
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "22",
    "fingerprint": "",
    "credit_type": "Visa",
    "credit_number": "1111",
    "credit_expires_month": "6",
    "credit_expires_year": "2026",
    "profile_id": "0",
    "payment_profile_id": "0",
    "first_name": "Jane",
    "birthday": "",
    "phone": "",
    "company": "",
    "last_name": "Doe",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42",
    "default": "1",
    "created": "2018-03-05 22:03:01",
    "last_update": "0000-00-00 00:00:00"
}
GET /payment/{id} Get Payment Method

Returns a single stored payment method by id.

Parameters
NameTypeRequiredDescriptionExample
id number Required Payment Method Id
Examples
Request
GET/payment/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "22",
    "fingerprint": "",
    "credit_type": "Visa",
    "credit_number": "1111",
    "credit_expires_month": "6",
    "credit_expires_year": "2026",
    "profile_id": "0",
    "payment_profile_id": "0",
    "first_name": "Jane",
    "birthday": "",
    "phone": "",
    "company": "",
    "last_name": "Doe",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42",
    "default": "1",
    "created": "2018-03-05 22:03:01",
    "last_update": "0000-00-00 00:00:00"
}
GET /payment/customer/{customer_id} Get Payment Methods By Customer

Returns all stored payment methods for the given customer, keyed by id.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
Examples
Request
GET/payment/customer/{customer_id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "22": {
        "id": "22",
        "fingerprint": "",
        "credit_type": "Visa",
        "credit_number": "1111",
        "credit_expires_month": "6",
        "credit_expires_year": "2026",
        "profile_id": "0",
        "payment_profile_id": "0",
        "first_name": "Jane",
        "birthday": "",
        "phone": "",
        "company": "",
        "last_name": "Doe",
        "address": "100 Main St",
        "address_2": "",
        "city": "Napa",
        "state": "CA",
        "zip": "94559",
        "country": "US",
        "customer_id": "42",
        "default": "1",
        "created": "2018-03-05 22:03:01",
        "last_update": "0000-00-00 00:00:00"
    }
}
PUT /payment/customer/{customer_id}/default/{id} Set Default Customer Payment Method

Marks the given payment method as the customer's default. Returns true on success.

Parameters
NameTypeRequiredDescriptionExample
customer_id number Required Customer Id
id number Required Payment Method Id
Examples
Request
PUT/payment/customer/{customer_id}/default/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
PUT /payment/{id} Update Payment Method

Updates the billing details on a stored payment method (only the keys sent are changed) and returns the updated record.

Parameters
NameTypeRequiredDescriptionExample
address string Optional Street Address
address_2 string Optional Unit Number
city string Optional City
company string Optional Company Name
first_name string Optional First Name
last_name string Optional Last Name
phone string Optional Phone Number
state string Optional State
title string Optional Address Title
zip string Optional Zip Code
id number Required Payment Method Id
Examples
Request
PUT/payment/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "address": "100 Main St",
    "city": "Napa",
    "state": "CA"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "22",
    "fingerprint": "",
    "credit_type": "Visa",
    "credit_number": "1111",
    "credit_expires_month": "6",
    "credit_expires_year": "2026",
    "profile_id": "0",
    "payment_profile_id": "0",
    "first_name": "Jane",
    "birthday": "",
    "phone": "",
    "company": "",
    "last_name": "Doe",
    "address": "100 Main St",
    "address_2": "",
    "city": "Napa",
    "state": "CA",
    "zip": "94559",
    "country": "US",
    "customer_id": "42",
    "default": "1",
    "created": "2018-03-05 22:03:01",
    "last_update": "0000-00-00 00:00:00"
}

Products

GET /products/{id} Get Product

Retrieve a single product by its id, including all catalog, pricing, wine, and media fields.

Parameters
NameTypeRequiredDescriptionExample
id number Required Product Id
Examples
Request
GET/products/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "842",
    "sku": "2021-CAB-750",
    "name": "2021 Estate Cabernet Sauvignon",
    "subtitle": "Napa Valley",
    "status": "Active",
    "website_visibility": "On",
    "price": "75.00",
    "retail_price": "85.00",
    "cost": "32.00",
    "quantity": "240",
    "starting_quantity": "300",
    "product_type": "Wine",
    "sc_product_type": "Wine",
    "tax_type": "Wine",
    "wine_type": "Red",
    "varietal": "Cabernet Sauvignon",
    "vintage": "2021",
    "bottle_size": "750mL",
    "bottle_count": "1",
    "appellation": "Napa Valley",
    "alcohol": "14.5",
    "featured_product": "Yes",
    "new_product": "No",
    "discount_eligible": "Yes",
    "free_shipping": "",
    "seo_slug": "2021-estate-cabernet-sauvignon",
    "volume_discount": {
        "12": "70.00",
        "6": "72.00"
    },
    "weight": "3.5",
    "image": "https://cdn.securecheckout.com/products/842/image.jpg",
    "created": "2026-01-14 09:22:00",
    "last_update": "2026-02-16 15:17:00"
}
GET /products Get All Products

Return the full list of active/inactive (non-archived) products. Not paginated.

Examples
Request
GET/products
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "842",
        "sku": "2021-CAB-750",
        "name": "2021 Estate Cabernet Sauvignon",
        "subtitle": "Napa Valley",
        "status": "Active",
        "website_visibility": "On",
        "price": "75.00",
        "retail_price": "85.00",
        "cost": "32.00",
        "quantity": "240",
        "starting_quantity": "300",
        "product_type": "Wine",
        "sc_product_type": "Wine",
        "tax_type": "Wine",
        "wine_type": "Red",
        "varietal": "Cabernet Sauvignon",
        "vintage": "2021",
        "bottle_size": "750mL",
        "bottle_count": "1",
        "appellation": "Napa Valley",
        "alcohol": "14.5",
        "featured_product": "Yes",
        "new_product": "No",
        "discount_eligible": "Yes",
        "free_shipping": "",
        "seo_slug": "2021-estate-cabernet-sauvignon",
        "volume_discount": {
            "12": "70.00",
            "6": "72.00"
        },
        "weight": "3.5",
        "image": "https://cdn.securecheckout.com/products/842/image.jpg",
        "created": "2026-01-14 09:22:00",
        "last_update": "2026-02-16 15:17:00"
    }
]
GET /products/archived Get All Archived Products

Return all products whose status is Archived.

Examples
Request
GET/products/archived
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "842",
        "sku": "2021-CAB-750",
        "name": "2021 Estate Cabernet Sauvignon",
        "subtitle": "Napa Valley",
        "status": "Archived",
        "website_visibility": "Off",
        "price": "75.00",
        "retail_price": "85.00",
        "cost": "32.00",
        "quantity": "240",
        "starting_quantity": "300",
        "product_type": "Wine",
        "sc_product_type": "Wine",
        "tax_type": "Wine",
        "wine_type": "Red",
        "varietal": "Cabernet Sauvignon",
        "vintage": "2021",
        "bottle_size": "750mL",
        "bottle_count": "1",
        "appellation": "Napa Valley",
        "alcohol": "14.5",
        "featured_product": "Yes",
        "new_product": "No",
        "discount_eligible": "Yes",
        "free_shipping": "",
        "seo_slug": "2021-estate-cabernet-sauvignon",
        "volume_discount": {
            "12": "70.00",
            "6": "72.00"
        },
        "weight": "3.5",
        "image": "https://cdn.securecheckout.com/products/842/image.jpg",
        "created": "2026-01-14 09:22:00",
        "last_update": "2026-02-16 15:17:00"
    }
]
POST /products Create Product

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
NameTypeRequiredDescriptionExample
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.
tax_type string Optional Wine, Merchandise, or Food.
wine_type string Optional Red, White, Rose, Sparkling, Dessert, Port/Fortified, Fruit/Berry, Mead, Other.
varietal string Optional One of the 84 supported varietals (e.g. Cabernet Sauvignon).
vintage string Optional Vintage year.
bottle_size string Optional e.g. 750mL, 1.5L (runtime list may override the static fallback).
appellation string Optional Appellation / region.
alcohol string Optional Alcohol by volume.
featured_product string Optional Yes or No.
new_product string Optional Yes or No.
discount_eligible string Optional Yes or No.
volume_discount object Optional Quantity-break map { "<qty>": "<price>" }, reverse-sorted by qty on write.
weight string Optional Shipping weight in lbs.
product_category string Optional Category id to attach the product to on create.
Examples
Request
POST/products
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "sku": "2021-CAB-750",
    "name": "2021 Estate Cabernet Sauvignon",
    "subtitle": "Napa Valley",
    "quantity": "300",
    "price": "75.00",
    "status": "Inactive",
    "product_type": "Wine",
    "sc_product_type": "Wine",
    "product_category": "12"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "842",
    "sku": "2021-CAB-750",
    "name": "2021 Estate Cabernet Sauvignon",
    "subtitle": "Napa Valley",
    "status": "Inactive",
    "website_visibility": "On",
    "price": "75.00",
    "retail_price": "85.00",
    "cost": "32.00",
    "quantity": "240",
    "starting_quantity": "300",
    "product_type": "Wine",
    "sc_product_type": "Wine",
    "tax_type": "Wine",
    "wine_type": "Red",
    "varietal": "Cabernet Sauvignon",
    "vintage": "2021",
    "bottle_size": "750mL",
    "bottle_count": "1",
    "appellation": "Napa Valley",
    "alcohol": "14.5",
    "featured_product": "Yes",
    "new_product": "No",
    "discount_eligible": "Yes",
    "free_shipping": "",
    "seo_slug": "2021-estate-cabernet-sauvignon",
    "volume_discount": {
        "12": "70.00",
        "6": "72.00"
    },
    "weight": "3.5",
    "image": "https://cdn.securecheckout.com/products/842/image.jpg",
    "created": "2026-01-14 09:22:00",
    "last_update": "2026-02-16 15:17:00"
}
POST /products/{id} Update Product

Update a product with the full edit form. Any writable attribute may be sent; volume_discount is a JSON quantity-break map.

Parameters
NameTypeRequiredDescriptionExample
id number Required Product Id
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.
tax_type string Optional Wine, Merchandise, or Food.
wine_type string Optional Red, White, Rose, Sparkling, Dessert, Port/Fortified, Fruit/Berry, Mead, Other.
varietal string Optional One of the 84 supported varietals (e.g. Cabernet Sauvignon).
vintage string Optional Vintage year.
bottle_size string Optional e.g. 750mL, 1.5L (runtime list may override the static fallback).
appellation string Optional Appellation / region.
alcohol string Optional Alcohol by volume.
featured_product string Optional Yes or No.
new_product string Optional Yes or No.
discount_eligible string Optional Yes or No.
volume_discount object Optional Quantity-break map { "<qty>": "<price>" }, reverse-sorted by qty on write.
weight string Optional Shipping weight in lbs.
product_category string Optional Category id to attach the product to on create.
Examples
Request
POST/products/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "name": "2021 Estate Cabernet Sauvignon",
    "subtitle": "Napa Valley",
    "price": "75.00",
    "retail_price": "85.00",
    "cost": "32.00",
    "quantity": "240",
    "status": "Active",
    "website_visibility": "On",
    "product_type": "Wine",
    "sc_product_type": "Wine",
    "tax_type": "Wine",
    "wine_type": "Red",
    "varietal": "Cabernet Sauvignon",
    "vintage": "2021",
    "bottle_size": "750mL",
    "appellation": "Napa Valley",
    "alcohol": "14.5",
    "featured_product": "Yes",
    "discount_eligible": "Yes",
    "volume_discount": {
        "12": "70.00",
        "6": "72.00"
    },
    "weight": "3.5"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "842",
    "sku": "2021-CAB-750",
    "name": "2021 Estate Cabernet Sauvignon",
    "subtitle": "Napa Valley",
    "status": "Active",
    "website_visibility": "On",
    "price": "75.00",
    "retail_price": "85.00",
    "cost": "32.00",
    "quantity": "240",
    "starting_quantity": "300",
    "product_type": "Wine",
    "sc_product_type": "Wine",
    "tax_type": "Wine",
    "wine_type": "Red",
    "varietal": "Cabernet Sauvignon",
    "vintage": "2021",
    "bottle_size": "750mL",
    "bottle_count": "1",
    "appellation": "Napa Valley",
    "alcohol": "14.5",
    "featured_product": "Yes",
    "new_product": "No",
    "discount_eligible": "Yes",
    "free_shipping": "",
    "seo_slug": "2021-estate-cabernet-sauvignon",
    "volume_discount": {
        "12": "70.00",
        "6": "72.00"
    },
    "weight": "3.5",
    "image": "https://cdn.securecheckout.com/products/842/image.jpg",
    "created": "2026-01-14 09:22:00",
    "last_update": "2026-02-16 15:17:00"
}
DELETE /products/{id} Delete Product

Permanently delete a product.

Parameters
NameTypeRequiredDescriptionExample
id number Required Product Id
Examples
Request
DELETE/products/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true

Categories

GET /categories/{id} Get Category

Retrieve a single category by id.

Parameters
NameTypeRequiredDescriptionExample
id number Required Category Id
Examples
Request
GET/categories/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "12",
    "name": "Cabernet Sauvignon",
    "slug": "cabernet-sauvignon",
    "display_brand": "Estate Wines",
    "display_title": "Our Cabernets",
    "description": "Age-worthy Cabernets from our estate vineyards.",
    "short_description": "Estate Cabernets.",
    "extended_description": "A deeper look at our Cabernet program and terroir.",
    "status": "Active",
    "website_visibility": "Active",
    "classification": "Collection",
    "enable_buy_collection": "Yes",
    "sort": "3",
    "current_offer": "0",
    "cm_campaign_id": "",
    "image": "https://cdn.securecheckout.com/categories/12/image.jpg",
    "image_2": "",
    "image_3": ""
}
GET /categories Get All Categories

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.

Parameters
NameTypeRequiredDescriptionExample
status string Optional Optional status filter: Active or Inactive.
Examples
Request
GET/categories
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
[
    {
        "id": "12",
        "name": "Cabernet Sauvignon",
        "slug": "cabernet-sauvignon",
        "display_brand": "Estate Wines",
        "display_title": "Our Cabernets",
        "description": "Age-worthy Cabernets from our estate vineyards.",
        "short_description": "Estate Cabernets.",
        "extended_description": "A deeper look at our Cabernet program and terroir.",
        "status": "Active",
        "website_visibility": "Active",
        "classification": "Collection",
        "enable_buy_collection": "Yes",
        "sort": "3",
        "current_offer": "0",
        "cm_campaign_id": "",
        "image": "https://cdn.securecheckout.com/categories/12/image.jpg",
        "image_2": "",
        "image_3": ""
    }
]
POST /categories Create Category

Create a category from the posted data.

Parameters
NameTypeRequiredDescriptionExample
name string Required Category name (required).
slug string Required Storefront URL segment (required).
display_brand string Optional Brand line shown with the category.
display_title string Required Display title / heading copy (required).
description string Optional Category description.
short_description string Optional Short description.
extended_description string Optional Extended description (retailer accounts only).
status string Optional Active, Inactive, or Archived.
website_visibility string Optional Active (Visible) or Inactive (Hidden).
classification string Optional Standard, Collection, Experience, Featured, Sampler, All, or Other (retailer only).
enable_buy_collection string Optional Yes or No (retailer only).
sort number Optional Sort order.
cm_campaign_id string Optional Campaign Monitor campaign id.
Examples
Request
POST/categories
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Body
{
    "name": "Cabernet Sauvignon",
    "slug": "cabernet-sauvignon",
    "display_brand": "Estate Wines",
    "display_title": "Our Cabernets",
    "description": "Age-worthy Cabernets from our estate vineyards.",
    "status": "Active",
    "website_visibility": "Active",
    "classification": "Collection",
    "sort": "3"
}
Response
Headers · 200
Content-Type: application/json
Body
{
    "id": "12",
    "name": "Cabernet Sauvignon",
    "slug": "cabernet-sauvignon",
    "display_brand": "Estate Wines",
    "display_title": "Our Cabernets",
    "description": "Age-worthy Cabernets from our estate vineyards.",
    "short_description": "Estate Cabernets.",
    "extended_description": "A deeper look at our Cabernet program and terroir.",
    "status": "Active",
    "website_visibility": "Active",
    "classification": "Collection",
    "enable_buy_collection": "Yes",
    "sort": "3",
    "current_offer": "0",
    "cm_campaign_id": "",
    "image": "https://cdn.securecheckout.com/categories/12/image.jpg",
    "image_2": "",
    "image_3": ""
}
DELETE /categories/{id} Delete Category

Permanently delete a category.

Parameters
NameTypeRequiredDescriptionExample
id number Required Category Id
Examples
Request
DELETE/categories/{id}
Headers
Content-Type: application/json
X-Auth-Token: XXXXXXXXX
Response
Headers · 200
Content-Type: application/json
Body
true
Public URL copied