Action API

Get, edit, or delete account actions by id; make updates to expiration dates and meta data for existing actions with the Shopwaive Action API

Create multiple promotional credits for the same customer with independent expiration dates or promotional periods with the Customer API PUT endpoint and then edit, delete, or update expirations and meta data with the Action API

When you make debits or deposits to a customers account using the Customer API PUT endpoint or via bulk increment import in the app, an amount field is created for that action. The amount field is only created for debits and deposits created using the bulk increment import in the app or the Customer API PUT endpoint

To create multiple promotional credits for the same customer, enable multiple expiration dates in Settings and use this guide to get started

When multiple expirations are enabled from 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 expirationdate. The debit transacted on the account balance is equal to the value of the amount field of the promotional credit action object. If the account has insufficient funds to transact a debit of amount (i.e. customer's available balance is less than the previous credited amount at the time the action is deleted), then the customer's balance is set equal to 0.00. Customer account balances cannot be negative

GET action endpoint

Fetch an action by id. When you make a PUT or POST request to the Customer API, a reference id is provided in the response body, this is equivalent to the url parameter actionid required for the Action API GET endpoint

When you make a GET request to the Customer API, a reference action id is provided for each action in the activity array. If a GET request to the Action API returns an amount field in the response body, this indicates the action was created using the Customer API PUT or through an increment bulk import action in the app

Get action

GEThttps://app.shopwaive.com/api/action/{actionid}

Path parameters

actionid*string

The id of the action to retrieve

Response

200default

Successfully fetched account action

Headers

Body

application/json

statusstring

validitystring

actionarray of object

Request

JavaScriptCurl

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

Response

[
  {
    "status": "success",
    "validity": "expires in less than 2 weeks",
    "action": [
      {
        "date": "2024-04-07T13:49:54.078Z",
        "note": "New balance reflects redemption of 3Q sales incentive and restock of inventory",
        "id": "4713HGUJZKULEC",
        "type": "rest_api",
        "transaction": 940.45,
        "expirationdate": "2024-04-20T13:49:53Z",
        "expires": "true",
        "amount": 25
      }
    ]
  }
]

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
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
note	Transaction note
type	Type of transaction (i.e. rest_api)
	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
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

partial_amount and remainingcan 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 expirationdate field is only applicable if the expires field is equal to true. If multiple expiry dates are enabled in Settings, the expirationdate applies to the action object defined in the activity array if a corresponding amount field is defined (i.e. the action was created using the Customer API PUT request or through an increment bulk import action using the drag-and-drop editor in the app)

If single expiry dates is enabled in Settings, thenexpirationdate field represents the date that was used to define the top-level account balance expiration at the time the action was created if expires was also equal to true

POST action endpoint

Update an actions expirationdate, expires, media or note 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.

Set action properties

POSThttps://app.shopwaive.com/api/action/{actionid}

Path parameters

actionid*string

The id of the action to retrieve

Body

application/json

Set action properties

notestring

expirationdatestring

expiresstring

Response

200default

Successfully set customer balance

Headers

Body

application/json

statusstring

Request

JavaScriptCurl

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

Response

[
  {
    "status": "success"
  }
]

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 April 21, 2028 or 2028-04-21 (i.e. YYYY-mm-dd)
expires*	If defined, true or false boolean string
media*	If defined, url of media associated with offer

Define the note or media 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 expires or expirationdate field values, then both expires and expirationdatefields are required in the request body. All request body fields can be updated simultaneously, however, at a minimum either note or both expires and expirationdateor media fields are required in the request body

Response Body

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

Debits made using the Customer APIPUTare not eligible for Action API POST updates or expiration, only deposits (i.e. amount values greater than 0)

Only the expirationdate, expires, and note field values can be updated on a previously created action; updates to amount are not allowed. If changes to amount are required, use the DELETE Action API, which triggers the same process as if the action expired; at the time the delete request is made if status is not equal to expired, a debit is created on the customer account balance equal to the value of the amount field of the promotional credit action object

DELETE action endpoint

Use this endpoint to delete an action. If an amount 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 amount in the action object.

If amount 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 amount (i.e. customer's available balance is less than the previous credited amount at the time the action is deleted), then the customer's balance is set equal to 0.00. Customer account balances cannot be negative

Deleting actions of type rest_api that do not have an amount field are allowed (actions created by the Customer API POST endpoint or via a bulk assign import 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 or POST endpoints

Delete action

DELETEhttps://app.shopwaive.com/api/action/{actionid}

Path parameters

actionid*string

The id of the action to delete

Response

200default

Successfully deleted account action

Headers

Body

application/json

statusstring

Request

JavaScriptCurl

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

Response

[
  {
    "status": "success"
  }
]

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)