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

GEThttps://app.shopwaive.com/api/customer/{customer_email}

Path parameters

customer_email*string

The email of the customer to retrieve

Response

200default

Successfully fetched customer account

Headers

Body

application/json

statusstring

customeridstring

emailstring

balancenumber

expirationdatestring

expiresstring

ordersarray of object

activityarray of object

Request

JavaScriptCurl

const response = await fetch('https://app.shopwaive.com/api/customer/{customer_email}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "status": "success",
    "customerid": "6659662610648",
    "email": "[e-mail]",
    "balance": 0,
    "expirationdate": "2025-01-19T18:50:15.75Z",
    "expires": "false",
    "orders": [
      {}
    ],
    "activity": [
      {
        "date": "2023-05-20T18:50:15.75Z",
        "note": "Refunded customer with store credit",
        "id": "1684608615750",
        "type": "adjusted",
        "transaction": "450.00",
        "expirationdate": "2022-05-20T18:50:15.738Z",
        "expires": "true",
        "status": "expired"
      }
    ]
  }
]

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

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

offers {} object

key	value
total	Sum of all eligible offers
items[]	List 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

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 [].action 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

POSThttps://app.shopwaive.com/api/customer

Body

application/json

Set customer data

customer_emailstring

balancenumber

notestring

expirationdatestring

expiresstring

Response

200default

Successfully set customer balance

Headers

Body

application/json

statusstring

idstring

customeridstring

emailstring

notestring

previousnumber

balancenumber

expirationdatestring

expiresstring

Request

JavaScriptCurl

const response = await fetch('https://app.shopwaive.com/api/customer', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {}
    ]),
});
const data = await response.json();

Response

[
  {
    "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"
  }
]

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

PUThttps://app.shopwaive.com/api/customer

Body

application/json

Adjust customer data

customer_emailstring

amountnumber

notestring

expirationdatestring

expiresstring

Response

200default

Successfully adjusted customer balance

Headers

Body

application/json

statusstring

idstring

customeridstring

emailstring

notestring

previousnumber

transactionnumber

balancenumber

expirationdatestring

expiresstring

Request

JavaScriptCurl

const response = await fetch('https://app.shopwaive.com/api/customer', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {}
    ]),
});
const data = await response.json();

Response

[
  {
    "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"
  }
]

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'

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