# Customer API

## `GET` customer endpoint

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

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FHt1gPQapwKfB28R7K3YZ%2Findex.yaml?alt=media&token=71291dd8-e621-45d8-bc52-5e4b316cd3f9>" path="/api/customer/{customer\_email}" method="get" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FHt1gPQapwKfB28R7K3YZ%2Findex.yaml?alt=media\&token=71291dd8-e621-45d8-bc52-5e4b316cd3f9)
{% endopenapi %}

### Header

<table><thead><tr><th width="328.3333333333333">key</th><th>value</th></tr></thead><tbody><tr><td>X-Shopwaive-Access-Token</td><td>Store's platform API key for store (required)</td></tr><tr><td>X-Shopwaive-Platform</td><td>Store's platform (required)</td></tr><tr><td>Content-Type</td><td>Content type</td></tr></tbody></table>

### 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    |

{% hint style="info" %}
Customer <mark style="color:blue;">`orders`</mark> array is only included in the response body if you append <mark style="color:blue;">**?orders=true**</mark> as a query parameter on the request route url
{% endhint %}

{% hint style="info" %}
The <mark style="color:blue;">`referralurl`</mark> is only returned if your Referral program is enabled. Learn more about Shopwaive's powerful [Referral program](https://docs.shopwaive.com/shopify/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
{% endhint %}

### offers {} object

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

{% hint style="info" %}
Customer <mark style="color:blue;">`offers`</mark> object is only included in the response body if you append <mark style="color:blue;">**?offers=true**</mark> as a query parameter on the request route url
{% endhint %}

### 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                                                                           |
| transaction[^1] | 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                                                     |

{% hint style="info" %} <mark style="color:blue;">`partial_amount`</mark> and <mark style="color:blue;">`remaining`</mark> can be equivalent in value. The edge case when <mark style="color:blue;">`partial_amount`</mark> is less than <mark style="color:blue;">`remaining`</mark> 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 <mark style="color:blue;">`remaining`</mark> because of a manual adjustment made to <mark style="color:blue;">`balance`</mark> for example. This means even though a <mark style="color:blue;">`remaining`</mark> amount is still attached to that offer, the customers <mark style="color:blue;">`balance`</mark> is not enough to cover the full remaining offer amount
{% endhint %}

{% hint style="info" %}
The <mark style="color:blue;">`offers`</mark> object conveniently filters the actions array and only returns eligible offers. A comprehensive list of all <mark style="color:blue;">`offers`</mark> including expired and redeemed can be found with other actions in the <mark style="color:blue;">`activity`</mark> array
{% endhint %}

### 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                               |
| transaction[^1] | Customer's available balance after action         |
| status          | If defined, status string (i.e. expire&#x64;**)** |
| amount          | If defined, amount the balance is incremented     |
| media           | If defined, url of media associated with offer    |

{% hint style="info" %}
Customer <mark style="color:blue;">`activity`</mark> array is only included in the response body if you append <mark style="color:blue;">**?activity=true**</mark> as a query parameter on the request route url
{% endhint %}

{% hint style="info" %}
The <mark style="color:blue;">**expirationdate**</mark> field is only applicable if the <mark style="color:blue;">**expires**</mark> field is equal to <mark style="color:blue;">**true**</mark>. If multiple expiry dates are enabled in Settings, the <mark style="color:blue;">**expirationdate**</mark> may apply to the <mark style="color:blue;">**action**</mark> object defined in the <mark style="color:blue;">**activity**</mark> array if a corresponding <mark style="color:blue;">**amount**</mark> field is defined. See <mark style="color:blue;">**Action API**</mark> for more details
{% endhint %}

## `POST` customer endpoint

Set a customer balance equal to value defined by <mark style="color:blue;">`balance`</mark>

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FqQCZRNecCtu7dpJgPoKq%2Findex.yaml?alt=media&token=09061bdc-9729-44e4-92a5-b1dd5f2698de>" path="/api/customer" method="post" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FqQCZRNecCtu7dpJgPoKq%2Findex.yaml?alt=media\&token=09061bdc-9729-44e4-92a5-b1dd5f2698de)
{% endopenapi %}

### 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 <mark style="color:blue;">`April 21, 2028`</mark> or <mark style="color:blue;">`2028-04-21`</mark> (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                 |

{% hint style="info" %}
**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.
{% endhint %}

## `PUT` customer endpoint

Increment a customer's existing balance by value defined by <mark style="color:blue;">`amount`</mark> debits are created by negative <mark style="color:blue;">`amount`</mark> values and deposits by positive values.

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FqQCZRNecCtu7dpJgPoKq%2Findex.yaml?alt=media&token=09061bdc-9729-44e4-92a5-b1dd5f2698de>" path="/api/customer" method="put" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FqQCZRNecCtu7dpJgPoKq%2Findex.yaml?alt=media\&token=09061bdc-9729-44e4-92a5-b1dd5f2698de)
{% endopenapi %}

### 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 <mark style="color:blue;">`April 21, 2028`</mark> or <mark style="color:blue;">`2028-04-21`</mark> (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 |

{% hint style="info" %}
**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`](#api-customer)
{% endhint %}

## `PUT` bulk customer endpoint

Create bulk offers, vouchers, promotions, or increment a customer's existing balance by value defined by <mark style="color:blue;">`amount`</mark> debits are created by negative <mark style="color:blue;">`amount`</mark> values and deposits by positive values. Use field <mark style="color:blue;">`scheduled`</mark> to schedule a transaction. If you desire to process the transaction imminently, do not include optional field <mark style="color:blue;">`scheduled`</mark> or assign it a string date in the past.&#x20;

<mark style="color:blue;">`transactions`</mark> is an array of objects that define actions, offers, debits, or credits. Max <mark style="color:blue;">`transactions`</mark> length per request is limited to 1,000. <mark style="color:blue;">`ref_id`</mark> 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](https://docs.shopwaive.com/shopify/offers),  <mark style="color:blue;">`ref_id`</mark> will be attached to the order attributes associated with redemption, viewable in the Shopify admin or via Shopify Orders API requests.

{% hint style="info" %}
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
{% endhint %}

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FC1cNPw7qxUIphIhD28yD%2Findex.yaml?alt=media&token=0e69b883-8291-435f-8862-ec13f5915ff2>" path="/api/customer/bulk" method="put" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FC1cNPw7qxUIphIhD28yD%2Findex.yaml?alt=media\&token=0e69b883-8291-435f-8862-ec13f5915ff2)
{% endopenapi %}

The response body includes <mark style="color:blue;">`scheduled`</mark>, which is the number of transactions scheduled imminently or in the future as defined by the request body. Response body field <mark style="color:blue;">`id`</mark> is the bulk import id to reference status of a pending offer scheduled.

[^1]: deprecated, unstable