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

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

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

get
Authorizations
Path parameters
actionidstringRequired

The id of the action to retrieve

Responses
200
Successfully fetched account action
application/json
get
GET /api/action/{actionid} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Accept: */*
{
  "status": "success",
  "email": "[email protected]",
  "validity": "expires in less than 2 weeks",
  "action": []
}
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. 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)

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

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

GET actions endpoint

Search actions by including any combination of query key value pairs id,email,created_at_min, or created_at_max 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().

// Example date and email constrained request

https://app.shopwaive.com/api/[email protected][email protected]&created_at_min=2024-09-22T04:51:20.144Z&created_at_max=2024-09-22T19:14:22.688Z

Get actions

get
Authorizations
Responses
200
Successfully fetched account actions
application/json
get
GET /api/actions HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Accept: */*
[]

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

post
Authorizations
Path parameters
actionidstringRequired

The id of the action to update

Body
notestringRequiredExample: New balance reflects redemption of 3Q sales incentive and restock of inventory
expirationdatestringRequiredExample: April 20, 2024
expiresstringRequiredExample: true
Responses
200
Successfully set customer balance
application/json
post
POST /api/action/{actionid} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "note": "New balance reflects redemption of 3Q sales incentive and restock of inventory",
  "expirationdate": "April 20, 2024",
  "expires": "true"
}
{
  "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)

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

Note: Debiting the original amount 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 ?remaining=true query to your request. Otherwise, the original amount will be used for the debit transaction

Delete action

delete
Authorizations
Path parameters
actionidstringRequired

The id of the action to delete

Responses
200
Successfully deleted account action
application/json
delete
DELETE /api/action/{actionid} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: YOUR_API_KEY
Accept: */*
{
  "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)

Last updated

Was this helpful?