# Customer API

## `GET` customer endpoint

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

{% openapi src="/files/1qfTeqobGa2kkMH5wHHf" 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="/files/iyVlr9YZyVLoEURXSiBZ" 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="/files/iyVlr9YZyVLoEURXSiBZ" 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`](/reference/rest-api-documentation/customer-api.md#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="/files/GZJCA4zE3Rl5lnPgUu8q" 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.shopwaive.com/reference/rest-api-documentation/customer-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.