Shopwaive API 2024-11
  • Shopwaive REST API
  • Quick Start
  • Reference
    • REST API documentation
      • Customer API
      • Action API
      • Order API
    • Shopwaive API rate limits
Powered by GitBook
On this page

Was this helpful?

  1. Reference
  2. REST API documentation

Customer API

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

PreviousREST API documentationNextAction API

Last updated 10 months ago

Was this helpful?

GET customer endpoint

Fetch 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

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

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

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.

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

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.

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.

The referralurl is only returned if your Referral program is enabled. Learn more about Shopwaive's powerful 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

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

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 , ref_id will be attached to the order attributes associated with redemption, viewable in the Shopify admin or via Shopify Orders API requests.

Referral program
Offers
POST

Adjust customer account balances in bulk

put
Authorizations
Body
Responses
200
Successfully adjusted customer balances
application/json
default
Unexpected error. Method not allowed
application/json
put
PUT /api/customer/bulk HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "transactions": []
}
{
  "status": "success",
  "scheduled": 1,
  "id": "1719027114459"
}

Get customer

get
Authorizations
Path parameters
customer_emailstringRequired

The email of the customer to retrieve

Responses
200
Successfully fetched customer account
application/json
default
Unexpected error. Method not allowed
application/json
get
GET /api/customer/{customer_email} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Accept: */*
{
  "status": "success",
  "customerid": "6659662610648",
  "email": "support@shopwaive.com",
  "balance": 0,
  "expirationdate": "2025-01-19T18:50:15.75Z",
  "expires": "false",
  "orders": []
}
  • GET customer endpoint
  • GETGet customer
  • Header
  • Response Body
  • offers {} object
  • offers.items [] object
  • activity[] object
  • POST customer endpoint
  • POSTSet customer account balance
  • Header
  • Request Body
  • Response Body
  • PUT customer endpoint
  • PUTAdjust customer account balance
  • Header
  • Request Body
  • Request Response
  • PUT bulk customer endpoint
  • PUTAdjust customer account balances in bulk

Set customer account balance

post
Authorizations
Body
customer_emailstringOptionalExample: support@shopwaive.com
balancenumberRequiredExample: 450
notestringOptionalExample: Refunded customer for Order #2839083271
expirationdatestringOptionalExample: 2024-05-20T18:50:15.738Z
expiresstringOptionalExample: false
Responses
200
Successfully set customer balance
application/json
default
Unexpected error. Method not allowed
application/json
post
POST /api/customer HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "customer_email": "support@shopwaive.com",
  "balance": 450,
  "note": "Refunded customer for Order #2839083271",
  "expirationdate": "2024-05-20T18:50:15.738Z",
  "expires": "false"
}
{
  "status": "success",
  "id": "43198OVZBGG1QO",
  "customerid": "6659662610648",
  "email": "support@shopwaive.com",
  "note": "Refunded customer for Order #2839083271",
  "previous": 0,
  "balance": 450,
  "expirationdate": "2024-05-20T18:50:15.738Z",
  "expires": "false"
}

Adjust customer account balance

put
Authorizations
Body
customer_emailstringOptionalExample: support@shopwaive.com
amountnumberRequiredExample: 250
notestringOptionalExample: Customer granted reward points as affiliate.
expirationdatestringOptionalExample: 2026-03-28T18:50:15.738Z
expiresstringOptionalExample: true
Responses
200
Successfully adjusted customer balance
application/json
default
Unexpected error. Method not allowed
application/json
put
PUT /api/customer HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 170

{
  "customer_email": "support@shopwaive.com",
  "amount": 250,
  "note": "Customer granted reward points as affiliate.",
  "expirationdate": "2026-03-28T18:50:15.738Z",
  "expires": "true"
}
{
  "status": "success",
  "id": "4713HGUJZKULEC",
  "customerid": "6659662610648",
  "email": "support@shopwaive.com",
  "note": "Refunded customer for Order #2839083271",
  "previous": 450,
  "transaction": 250,
  "balance": 700,
  "expirationdate": "2026-03-28T18:50:15.738Z",
  "expires": "true"
}