# Action API

{% hint style="success" %}
Create multiple promotional credits for the same customer with independent expiration dates or promotional periods with the [Customer API PUT endpoint](https://api.shopwaive.com/reference/customer-api#increment-customer-endpoint) and then edit, delete, or update expirations and meta data with the [Action API](https://api.shopwaive.com/reference/rest-api-documentation/action-api)
{% endhint %}

{% hint style="info" %}
When you make debits or deposits to a customers account using the  [Customer API PUT endpoint](https://api.shopwaive.com/reference/customer-api#increment-customer-endpoint) or via [bulk increment import ](https://docs.shopwaive.com/shopify/store-credit/import-accounts#increment-balances-using-the-increment-column)in the app, an <mark style="color:blue;">`amount`</mark> field is created for that action. The <mark style="color:blue;">`amount`</mark> field is only created for debits and deposits created using the bulk increment import in the app or the Customer API PUT endpoint&#x20;
{% endhint %}

{% hint style="info" %}
To create multiple promotional credits for the same customer, enable multiple expiration dates in [Settings](https://docs.shopwaive.com/product-tour/dashboard#settings) and use this guide to get started
{% endhint %}

{% hint style="success" %}
When multiple expirations are enabled from [Settings](https://docs.shopwaive.com/product-tour/dashboard#settings), and if a promotional credit associated with an action expires, then a debit is created on the customer account balance automatically at the time defined by <mark style="color:blue;">`expirationdate`</mark>. The debit transacted on the account balance is equal to the value of the <mark style="color:blue;">`amount`</mark> field of the promotional credit action object. If the account has insufficient funds to transact a debit of <mark style="color:blue;">`amount`</mark> (i.e. customer's available <mark style="color:blue;">`balance`</mark> is less than the previous credited <mark style="color:blue;">`amount`</mark> at the time the action is deleted), then the customer's balance is set equal to 0.00. Customer account balances cannot be negative
{% endhint %}

## `GET` action endpoint

Fetch an action by <mark style="color:blue;">`id`</mark>. When you make a [PUT](https://api.shopwaive.com/reference/customer-api#adjust-customer-balance) or [POST](https://api.shopwaive.com/reference/customer-api#set-customer-balance) request to the [Customer API](https://api.shopwaive.com/reference/rest-api-documentation/customer-api), a reference <mark style="color:blue;">`id`</mark> is provided in the response body, this is equivalent to the url parameter <mark style="color:blue;">`actionid`</mark> required for the [Action API](https://api.shopwaive.com/reference/rest-api-documentation/action-api) [GET](#get-action) endpoint

{% hint style="info" %}
When you make a [GET](https://api.shopwaive.com/reference/customer-api#get-customer-account-balance-and-transactions) request to the [Customer API](https://api.shopwaive.com/reference/rest-api-documentation/customer-api), a reference action <mark style="color:blue;">`id`</mark> is provided for each action in the activity array. If a [GET](#get-action) request to the [Action API](https://api.shopwaive.com/reference/rest-api-documentation/action-api) returns an <mark style="color:blue;">`amount`</mark> field in the response body, this indicates the action was created using the Customer API [PUT](https://api.shopwaive.com/reference/customer-api#adjust-customer-balance) or through an [increment bulk import](https://docs.shopwaive.com/shopify/store-credit/import-accounts#increment-balances-using-the-increment-column) action in the app
{% endhint %}

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media&token=835f83fe-5d2d-497c-9100-70bcc526b896>" path="/api/action/{actionid}" method="get" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media\&token=835f83fe-5d2d-497c-9100-70bcc526b896)
{% 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                                   |
| validity | Description of time left until expiration        |
| action   | Object of action requested                       |
| email    | Customer email address                           |
| message  | If exists, a tip or hint for developer reference |

### action\[] object

| key             | value                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------- |
| expirationdate  | Date the action amount or balance expires                                                     |
| expires         | True or false boolean string                                                                  |
| date            | Date action was created or last updated                                                       |
| id              | Action id. This is set to the order id if created by an order or line item of an order        |
| note            | Transaction note                                                                              |
| type            | Type of transaction (i.e. *rest\_api*)                                                        |
| transaction[^1] | Customer's available balance after action                                                     |
| lineitemid      | If defined, line item id associated or resulted in creation of action amount                  |
| orderid         | If defined, order id associated with the latest redemption event of action amount             |
| 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                                                |
| 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                                              |
| partial\_amount | If defined, remaining available offer amount (i.e. constrained by current available balance)  |
| remaining       | If defined, remaining available offer amount (i.e. constrained by previous order transaction) |
| validity        | Description of time left until expiration                                                     |

{% hint style="success" %} <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 <mark style="color:blue;">`balance`</mark> 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;">`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](https://docs.shopwaive.com/product-tour/dashboard#settings), the <mark style="color:blue;">`expirationdate`</mark> applies 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 (i.e. the action was created using the [Customer API PUT](https://api.shopwaive.com/reference/customer-api#adjust-customer-balance) request or through an [increment bulk import](https://docs.shopwaive.com/shopify/store-credit/import-accounts#increment-balances-using-the-increment-column) action using the drag-and-drop editor in the app)
{% endhint %}

{% hint style="info" %}
If single expiry dates is enabled in [Settings](https://docs.shopwaive.com/product-tour/dashboard#settings), then<mark style="color:blue;">`expirationdate`</mark> field represents the date that was used to define the top-level account balance expiration at the time the action was created if <mark style="color:blue;">`expires`</mark> was also equal to <mark style="color:blue;">**true**</mark>
{% endhint %}

## `GET` actions endpoint

Search actions by including any combination of query key value pairs <mark style="color:blue;">`id`</mark>,<mark style="color:blue;">`email`</mark>,<mark style="color:blue;">`created_at_min`</mark>, or <mark style="color:blue;">`created_at_max`</mark> appended to the /api/actions endpoint. A maximum of 250 records per request are returned in the response body. Dates should use ISOString format when appended as a query string, for example, new Date().toISOString().

{% code overflow="wrap" %}

```javascript
// Example date and email constrained request

https://app.shopwaive.com/api/actions?email=support@shopwaive.com&created_at_min=2024-09-22T04:51:20.144Z&created_at_max=2024-09-22T19:14:22.688Z
```

{% endcode %}

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FGefvykL1vwWE5CCRQxHF%2Findex.yaml?alt=media&token=27d7b494-7545-4226-84f3-d9b0af8ae446>" path="/api/actions" method="get" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FGefvykL1vwWE5CCRQxHF%2Findex.yaml?alt=media\&token=27d7b494-7545-4226-84f3-d9b0af8ae446)
{% endopenapi %}

## `POST` action endpoint

Update an actions <mark style="color:blue;">`expirationdate`</mark>, <mark style="color:blue;">`expires`</mark>, <mark style="color:blue;">`media`</mark> or <mark style="color:blue;">`note`</mark> field(s). This route is useful when updating the validity of an existing promotional credit thats dynamic in nature, for example, when events or customer actions trigger a customers eligibility or access to the promotional credit.

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media&token=835f83fe-5d2d-497c-9100-70bcc526b896>" path="/api/action/{actionid}" method="post" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media\&token=835f83fe-5d2d-497c-9100-70bcc526b896)
{% 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                                                                                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| note\*           | If defined, description of transaction                                                                                                                                                |
| expirationdate\* | If defined, 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\*        | If defined, true or false boolean string                                                                                                                                              |
| media\*          | If defined, url of media associated with offer                                                                                                                                        |

{% hint style="info" %}
Define the <mark style="color:blue;">`note`</mark> or <mark style="color:blue;">`media`</mark> fields in the request body (optional) if you desire to change the note string or media url, respectively, these field can be defined in the request body without any other required fields. If you desire to update the <mark style="color:blue;">`expires`</mark> or <mark style="color:blue;">`expirationdate`</mark> field values, then both <mark style="color:blue;">`expires`</mark> and <mark style="color:blue;">`expirationdate`</mark>fields are required in the request body. All request body fields can be updated simultaneously, however, at a minimum either <mark style="color:blue;">`note`</mark> or both <mark style="color:blue;">`expires`</mark> and <mark style="color:blue;">`expirationdate`</mark>or <mark style="color:blue;">`media`</mark> fields are required in the request body
{% endhint %}

### Response Body

| key    | value                         |
| ------ | ----------------------------- |
| status | Status message (i.e. success) |

{% hint style="success" %}
Debits made using the Customer API[`PUT`](https://api.shopwaive.com/reference/customer-api#adjust-customer-balance)are not eligible for Action API [POST](#set-action-properties) updates or expiration, only deposits (i.e. <mark style="color:blue;">`amount`</mark> values greater than 0)
{% endhint %}

{% hint style="info" %}
Only the <mark style="color:blue;">`expirationdate`</mark>, <mark style="color:blue;">`expires`</mark>, and <mark style="color:blue;">`note`</mark> field values can be updated on a previously created action; updates to <mark style="color:blue;">`amount`</mark> are not allowed. If changes to <mark style="color:blue;">`amount`</mark> are required, use the [DELETE](#delete-action) Action API, which triggers the same process as if the action expired; at the time the delete request is made if <mark style="color:blue;">`status`</mark> is not equal to <mark style="color:blue;">**expired**</mark>, a debit is created on the customer account balance equal to the value of the <mark style="color:blue;">`amount`</mark> field of the promotional credit action object
{% endhint %}

## `DELETE` action endpoint

Use this endpoint to delete an action. If an <mark style="color:blue;">`amount`</mark> field is defined for the action, deleting the action will automatically reverse the increment the action imposed on the balance by triggering either a debit or deposit to the customer account balance equal to the negated value of <mark style="color:blue;">`amount`</mark> in the <mark style="color:blue;">`action`</mark> object.&#x20;

{% hint style="info" %}
If <mark style="color:blue;">`amount`</mark> is defined for the action, requests to this endpoint will automatically reverse the credit deposited or amount debited when the action was created. If the account has insufficient funds to transact a debit of <mark style="color:blue;">`amount`</mark> (i.e. customer's available <mark style="color:blue;">`balance`</mark> is less than the previous credited <mark style="color:blue;">`amount`</mark> at the time the action is deleted), then the customer's balance is set equal to 0.00. Customer account balances cannot be negative

**Note:** Debiting the original <mark style="color:blue;">`amount`</mark> of the action is useful in most cases when earned cash or points were a result of an order created that was later cancelled or refunded. Even if the earned cash or points were already spent, deleting the action will attempt to debit any existing balance to recoup the earned credit

If an action amount has been redeemed or partially redeemed already, and you wish to only debit the remaining amount, append <mark style="color:blue;">**?remaining=true**</mark> query to your request. Otherwise, the original <mark style="color:blue;">`amount`</mark> will be used for the debit transaction
{% endhint %}

{% hint style="success" %}
Deleting actions of type <mark style="color:blue;">`rest_api`</mark> that do not have an <mark style="color:blue;">`amount`</mark> field are allowed (actions created by the Customer API [<mark style="color:blue;">POST</mark>](https://api.shopwaive.com/reference/customer-api#set-customer-endpoint) endpoint or via a [bulk assign import](https://docs.shopwaive.com/shopify/store-credit/import-accounts#assign-balances-using-the-balance-column) action in the app), however, no automatic adjustments to an account balance are triggered as a result of deleting the action, and if required, balance adjustments must be created by your integration with an additional request to the [Customer API PUT](https://api.shopwaive.com/reference/customer-api#increment-customer-endpoint) or [POST](https://api.shopwaive.com/reference/customer-api#set-customer-endpoint) endpoints
{% endhint %}

{% hint style="success" %}
If an order triggers the creation of the action (i.e. via Shopify Flow and the Increment balance action), then the action <mark style="color:blue;">**`id`**</mark> is automatically set equal to the order id that created it. Therefore, if multiple deposits occur on the same order, to uniquely define the action object send the <mark style="color:blue;">**Increment balance**</mark> Shopify Flow action the Line Item ID by using a <mark style="color:blue;">**For each**</mark> loop action in the Shopify Flow to make the deposits on a line item level. Then you can use the [<mark style="color:blue;">DELETE</mark>](#delete-action-endpoint), [<mark style="color:blue;">POST</mark>](#post-action-endpoint), or [<mark style="color:blue;">GET</mark>](#get-action-endpoint) endpoints using the <mark style="color:blue;">**`lineitemid`**</mark> of the action instead of <mark style="color:blue;">**`id`**</mark> for the<mark style="color:blue;">**`{actionid}`**</mark>path parameter.&#x20;

Otherwise, if multiple actions are associated with the<mark style="color:blue;">**`{actionid}`**</mark>sent in the endpoint path, then each action associated with the order will be deleted and debited. If this is your intent, use an order id for the<mark style="color:blue;">**`{actionid}`**</mark>path parameter to conveniently delete all actions (i.e. deposits) associated with that order. The deletion of each action will create an associated debit as described above
{% endhint %}

{% openapi src="<https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media&token=835f83fe-5d2d-497c-9100-70bcc526b896>" path="/api/action/{actionid}" method="delete" %}
[index.yaml](https://2430267771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7BwDfJhPObShd4z9nqx%2Fuploads%2FrmFrmmYnC4xCfYS29vzO%2Findex.yaml?alt=media\&token=835f83fe-5d2d-497c-9100-70bcc526b896)
{% 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 Response

| key    | value                           |
| ------ | ------------------------------- |
| status | Status message (i.e. *success*) |

[^1]: deprecated, unstable