order-sync

Overview

Sync an externally processed order into WellnessLiving without charging the customer.

The OrderSync endpoint allows external e-commerce and point-of-sale systems to push completed orders into WellnessLiving. Because payment has already been collected externally, no charge is applied by WellnessLiving — the endpoint creates the purchase record and fulfils the items only.

Endpoint Details

Method: POST

Base URL: https://uat-api.wellnessliving.io

Content-Type: application/json

Request Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token from OAuth 2.0 `client_credentials` flow
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Send a JSON object in the request body. All top-level required fields must be present. Nested arrays use zero-indexed objects.

Top-level Fields

Field	Type	Required	Description
`k_business`	string	Yes	Business primary key (`RsBusinessSql`). Identifies the WellnessLiving business account.
`k_location`	string	Yes	Location primary key (`RsLocationSql`). The location where the order is being placed.
`uid`	string	Yes	User primary key (`PassportLoginSql`). The client on whose behalf the order is being created.
`text_order`	string	Yes	Unique external order ID. Max 255 characters. Acts as an idempotency key — re-submitting the same value returns the existing `k_purchase` without duplication.
`a_purchase_item`	array	Yes	Array of line items to include in the order. See `a_purchase_item` fields below.
`a_pay_form`	array	Yes	Array of payment methods used. Amounts must sum to the total order value.
`id_mode`	integer	No	Operation mode identifier (`ModeSid`). Controls how the order is processed.
`m_tip`	string	No	Tip amount as a decimal string. e.g. `"5.00"`. Business must have tips enabled.
`text_receipt_note`	string	No	Custom note to appear on the receipt.

`a_purchase_item` — Line Item Fields

Each element of the a_purchase_item array represents one line item. Include one object per item.

Field	Type	Required	Description
`id_purchase_item`	integer	Yes	Item type identifier (`RsPurchaseItemSid`). `1` = Appointment, `2` = Session / Class pass, `9` = Product.
`k_id`	string	Yes	Primary key of the item to purchase (product key, membership key, etc.).
`i_quantity`	integer	Yes	Quantity of this item to purchase.
`m_price_manual`	string	No	Price override as a decimal string. e.g. `"25.00"`. Overrides the item's listed price.
`k_shop_product_option`	string	No	Product option key. Use when the product has variants (size, colour, etc.).
`a_tax`	array	No	Custom tax overrides. Each element should contain the tax key and amount.
`a_config`	object	No	Item-specific configuration. Structure varies by item type. See `a_config` sub-fields below.

`a_config` — Item Configuration Sub-fields

The a_config object is passed inside each a_purchase_item entry. Its accepted fields depend on the item type being purchased.

Promotions & Memberships

Field	Type	Required	Description
`dl_start`	string	No	Start date for the promotion in `YYYY-MM-DD` format.
`is_renew`	boolean	No	Whether to auto-renew the membership. `true` or `false`.
`m_prorate_custom`	string	No	Custom proration amount as a decimal string.

Gift Cards (`id_purchase_item = COUPON`)

Field	Type	Required	Description
`s_code`	string	No	Unique gift card code to assign.
`dt_send_local`	string	No	Scheduled send datetime in local time (`YYYY-MM-DD HH:MM:SS`).
`a_quick_gift`	array	No	Quick-gift configuration array.

Tips (`id_purchase_item = APPOINTMENT_TIP`)

Field	Type	Required	Description
`k_staff`	string	No	Staff member key. Assigns the tip to a specific staff member.

`a_pay_form` — Payment Method Fields

Each element of the a_pay_form array represents one payment method. Multiple payment methods are allowed and their amounts must sum to the full order total.

Field	Type	Required	Description
`id_pay_method`	integer	Yes	Payment method identifier (`RsPayMethodSid`). `11` = External payment (already collected outside WellnessLiving).
`m_amount`	string	Yes	Amount applied from this payment method as a decimal string. e.g. `"50.00"`.
`k_pay_method`	string	No	Card-on-file key. Required when charging a saved payment method.
`m_surcharge`	string	No	Surcharge amount as a decimal string applied to this payment method.

Request Example

{
  "k_business": "100",
  "k_location": "25",
  "uid": "9999",
  "text_order": "EXT-ORDER-20240315-0042",
  "text_receipt_note": "Imported from external store",
  "a_purchase_item": [
    {
      "id_purchase_item": 3,
      "k_id": "555",
      "i_quantity": 1,
      "m_price_manual": "45.00",
      "k_shop_product_option": "",
      "a_tax": [],
      "a_config": []
    }
  ],
  "a_pay_form": [
    {
      "id_pay_method": 11,
      "m_amount": "45.00"
    }
  ]
}

Responses

200 OK — Success

The order was created successfully. Returns the WellnessLiving purchase key.

{
  "k_purchase": "8888-7777-6666"
}

Response Fields

Field	Type	Description
`k_purchase`	string	The WellnessLiving purchase primary key for the created order.

Error Responses

All error responses return HTTP 4xx with a JSON body containing a sid_exception field that identifies the specific error condition.

Error Response Format

{
  "sid_exception": "pay-amount-mismatch",
  "text_message": "Payment amounts do not match order total."
}

Error Codes

`sid_exception`	HTTP	Description
`access`	403	The authenticated user does not have the `STORE_SELL` privilege required to process orders at this location.
`pay-amount-mismatch`	422	The sum of all `m_amount` values in `a_pay_form` does not equal the total order value. Adjust payment amounts.
`order-exists`	200	A purchase with the given `text_order` already exists. The existing `k_purchase` is returned — no duplicate is created (idempotent).
`access-foreign`	403	The appointment referenced in `a_purchase_item` belongs to a different user than the `uid` provided.
`purchase-item-location`	422	The item referenced by `k_id` is not available for purchase at the location specified by `k_location`.
`flagged`	403	The user (`uid`) is flagged at the specified location and cannot make purchases.
`tip-disable`	422	`m_tip` was provided but tips are disabled for this business. Remove the `m_tip` field.
`product-nx`	404	No product was found matching the provided `k_id`. Verify the product key is correct and belongs to this business.
`code-x`	409	The gift card code in `s_code` already exists. Use a unique code value.
`prorate-start`	422	The `dl_start` date for a membership proration conflicts with existing membership dates.

Idempotency

The text_order field serves as an idempotency key. If a request is submitted with a text_order value that has already been successfully processed, the endpoint will return HTTP 200 with the original k_purchase instead of creating a duplicate order.

⚠️ Important: Always use a unique, stable external order identifier as text_order. Do not generate a new random value per retry — use your own system's order ID so that network retries automatically deduplicate without creating duplicate purchases.

/v1/ecommerce/order/sync

POST /v1/integration/ecommerce/order-sync#

Overview#

Endpoint Details#

Request Headers#

Request Body#

Top-level Fields#

a_purchase_item — Line Item Fields#

a_config — Item Configuration Sub-fields#

Promotions & Memberships#

Gift Cards (id_purchase_item = COUPON)#

Tips (id_purchase_item = APPOINTMENT_TIP)#

a_pay_form — Payment Method Fields#

Request Example#

Responses#

200 OK — Success#

Response Fields#

Error Responses#

Error Response Format#

Error Codes#

Idempotency#

Request

Responses

POST /v1/integration/ecommerce/order-sync

Overview

Endpoint Details

Request Headers

Request Body

Top-level Fields

`a_purchase_item` — Line Item Fields

`a_config` — Item Configuration Sub-fields

Promotions & Memberships

Gift Cards (`id_purchase_item = COUPON`)

Tips (`id_purchase_item = APPOINTMENT_TIP`)

`a_pay_form` — Payment Method Fields

Request Example

Responses

200 OK — Success

Response Fields

Error Responses

Error Response Format

Error Codes

Idempotency