Customer API
Get customer store credit balances; make adjustments based on their actions with the Shopwaive Customer API
GET
customer endpoint
GET
customer endpointFetch customer account details, including account balance, a ledger of account transactions, and customer orders.
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 |
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
POST
customer endpointSet a customer balance equal to value defined by 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 |
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 |
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
PUT
customer endpointIncrement a customer's existing balance by value defined by amount
debits are created by negative amount
values and deposits by positive values.
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 |
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 |
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
PUT
bulk customer endpointCreate 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 support@shopwaive.com to notify us of your interest and we can enable bulk operations on your store
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.
Last updated