Customer API

Get customer store credit balances; make adjustments based on their actions with the Shopwaive Customer API

GET customer endpoint

Fetch customer account details, including account balance, a ledger of account transactions, and customer orders.

Get customer

get

/api/customer/{customer_email}

Authorizations

Path parameters

customer_emailstringrequired

The email of the customer to retrieve

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.shopwaive.com/api/customer/{customer_email}' \
  --header 'X-Shopwaive-Access-Token: YOUR_API_KEY'

200

default

200

{
  "status": "success",
  "customerid": "6659662610648",
  "email": "[e-mail]",
  "balance": 0,
  "expirationdate": "2025-01-19T18:50:15.75Z",
  "expires": "false",
  "orders": []
}

Successfully fetched customer account

Header

key	value
X-Shopwaive-Access-Token	Store's platform API key for store (required)
X-Shopwaive-Platform	Store's platform (required)
Content-Type	Content type

Response Body

key	value
status	Status message
customerid	Customer id associated with store's platform
email	Customer email address
balance	Customer's available balance
expirationdate	Date of balance expiration
expires	True or false boolean string
activity	If requested, array of account action objects
orders	If requested, array of account order objects
offers	If requested, object of sum and list of offers
referralurl	If available, referral link to earn rewards

Customer orders array is only included in the response body if you append ?orders=true as a query parameter on the request route url

The referralurl is only returned if your Referral program is enabled. Learn more about Shopwaive's powerful Referral program for customers and affiliates. If new customers sign up using the referral link, you can choose to reward one or both the referrer and new customer

offers {} object

key	value
total	Sum of all eligible offers
items	Array of eligible offers

Customer offers object is only included in the response body if you append ?offers=true as a query parameter on the request route url

offers.items [] object

key	value
segment_query	If defined, customer segment query string i.e. customer_tags CONTAINS 'FALL2023'
collectionids	If defined, collection ids available for redemption
productids	If defined, product ids available for redemption
media	If defined, url of media associated with offer
amount	Amount of original offer
date	Date item is created or updated
note	Title of offer
id	Action id
type	Type of transaction
	Customer's available balance after action
expirationdate	Date the action amount or balance expires
expires	True or false boolean string
orderid	If defined, reference order id associated with last redemption
remaining	If defined, remaining available offer amount (i.e. constrained by previous order transaction)
status	If defined, status of offer (i.e. redeemed, expired, partial)
partial_amount	If defined, remaining available offer amount (i.e. constrained by current available balance)
validity	Description of time left until expiration

partial_amount and remaining can be equivalent in value. The edge case when partial_amount is less than remaining is when a previous order partially reduces the original offer available redemption amount at the same time that a customers available balance is less than remaining because of a manual adjustment made to balance for example. This means even though a remaining amount is still attached to that offer, the customers balance is not enough to cover the full remaining offer amount

The offers object conveniently filters the actions array and only returns eligible offers. A comprehensive list of all offers including expired and redeemed can be found with other actions in the activity array

activity[] object

key	value
expirationdate	Date the action amount or balance expires
expires	True or false boolean string
date	Date of transaction
id	Action id
note	Transaction note
type	Type of transaction
	Customer's available balance after action
status	If defined, status string (i.e. expired)
amount	If defined, amount the balance is incremented
media	If defined, url of media associated with offer

Customer activity array is only included in the response body if you append ?activity=true as a query parameter on the request route url

The expirationdate field is only applicable if the expires field is equal to true. If multiple expiry dates are enabled in Settings, the expirationdate may apply to the action object defined in the activity array if a corresponding amount field is defined. See Action API for more details

POST customer endpoint

Set a customer balance equal to value defined by balance

Set customer account balance

post

/api/customer

Authorizations

Body

customer_emailstring

Example: [e-mail]

balancenumberrequired

Example: 450

notestring

Example: Refunded customer for Order #2839083271

expirationdatestring

Example: 2024-05-20T18:50:15.738Z

expiresstring

Example: false

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://app.shopwaive.com/api/customer' \
  --header 'X-Shopwaive-Access-Token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"customer_email":"[e-mail]","balance":450,"note":"Refunded customer for Order #2839083271","expirationdate":"2024-05-20T18:50:15.738Z","expires":"false"}'

200

default

200

{
  "status": "success",
  "id": "43198OVZBGG1QO",
  "customerid": "6659662610648",
  "email": "[e-mail]",
  "note": "Refunded customer for Order #2839083271",
  "previous": 0,
  "balance": 450,
  "expirationdate": "2024-05-20T18:50:15.738Z",
  "expires": "false"
}

Successfully set customer balance

Header

key	value
X-Shopwaive-Access-Token	Store's platform API key for store (required)
X-Shopwaive-Platform	Store's platform (required)
Content-Type	Content type

Request Body

key	value
customer_email*	Customer email address
balance*	Value to assign to customer available balance
note	Description of transaction
expirationdate	Date of balance expiration. Accepted formats include April 21, 2028 or 2028-04-21 (i.e. YYYY-mm-dd)
expires	True or false boolean string

Response Body

key	value
id	Action id created by request
status	Status message
customerid	Customer id associated with store's platform
email	Customer email address
note	Description of transaction
previous	Customer's balance prior to request
balance	Customer's balance after successful request
expirationdate	Date of balance expiration
expires	True or false boolean string

Good to know: This API method sets customer balance to a predefined decimal value (i.e. independent of locale or currency). Currency is chosen within the store platform.

PUT customer endpoint

Increment a customer's existing balance by value defined by amount debits are created by negative amount values and deposits by positive values.

Adjust customer account balance

put

/api/customer

Authorizations

Body

customer_emailstring

Example: [e-mail]

amountnumberrequired

Example: 250

notestring

Example: Customer granted reward points as affiliate.

expirationdatestring

Example: 2026-03-28T18:50:15.738Z

expiresstring

Example: true

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://app.shopwaive.com/api/customer' \
  --header 'X-Shopwaive-Access-Token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"customer_email":"[e-mail]","amount":250,"note":"Customer granted reward points as affiliate.","expirationdate":"2026-03-28T18:50:15.738Z","expires":"true"}'

200

default

200

{
  "status": "success",
  "id": "4713HGUJZKULEC",
  "customerid": "6659662610648",
  "email": "[e-mail]",
  "note": "Refunded customer for Order #2839083271",
  "previous": 450,
  "transaction": 250,
  "balance": 700,
  "expirationdate": "2026-03-28T18:50:15.738Z",
  "expires": "true"
}

Successfully adjusted customer balance

Header

key	value
X-Shopwaive-Access-Token	Store's platform API key for store (required)
X-Shopwaive-Platform	Store's platform (required)
Content-Type	Content type

Request Body

key	value
customer_email*	Customer email address
amount*	Value to increment (add or subtract) to customer available balance
note	Description of transaction
expirationdate	Date the incremented amount expires if multiple expiration dates are enabled in Settings. If only single expiration dates are enabled, this date defines the total balance expiration. Accepted formats include April 21, 2028 or 2028-04-21 (i.e. YYYY-mm-dd)
expires	True or false boolean string
media	If defined, url of media associated with offer
segment_query	If defined, customer_email should be left blank. i.e. customer_tags CONTAINS 'FALL2023'
collectionids	If defined, collection ids available for redemption
productids	If defined, product ids available for redemption

Request Response

key	value
id	Action id created by request
status	Status message
customerid	Customer id associated with store's platform
email	Customer email address
note	Description of transaction
previous	Customer's balance prior to request
transaction	Value of transaction delta
balance	Customer's balance after successful request
expirationdate	Date of balance expiration
expires	True or false boolean string
media	If defined, url of media associated with offer

Tip: amount is defined as the total amount to add or subtract to the existing customer balance. Customers that do not yet have a Shopify account are automatically created. To set customer balance to a predefined amount, instead use Customer API POST

PUT bulk customer endpoint

Create bulk offers, vouchers, promotions, or increment a customer's existing balance by value defined by amount debits are created by negative amount values and deposits by positive values. Use field scheduled to schedule a transaction. If you desire to process the transaction imminently, do not include optional field scheduled or assign it a string date in the past.

transactions is an array of objects that define actions, offers, debits, or credits. Max transactions length per request is limited to 1,000. ref_id is a convenient optional reference field id for tracking of the offer transaction as needed by other 3rd party CRM, CDP, backend servers, or other integrations. If used in conjunction with Offers, ref_id will be attached to the order attributes associated with redemption, viewable in the Shopify admin or via Shopify Orders API requests.

To use the bulk endpoint, you must first contact [e-mail] to notify us of your interest and we can enable bulk operations on your store

Adjust customer account balances in bulk

put

/api/customer/bulk

Authorizations

Body

transactionsobject[]

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://app.shopwaive.com/api/customer/bulk' \
  --header 'X-Shopwaive-Access-Token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"transactions":[]}'

200

default

200

{
  "status": "success",
  "scheduled": 1,
  "id": "1719027114459"
}

Successfully adjusted customer balances

The response body includes scheduled, which is the number of transactions scheduled imminently or in the future as defined by the request body. Response body field id is the bulk import id to reference status of a pending offer scheduled.