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
GET
action endpointFetch 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
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 |
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 remaining
can 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
POST
action endpointUpdate 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.
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 |
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 expirationdate
fields are required in the request body. All request body fields can be updated simultaneously, however, at a minimum either note
or both expires
and expirationdate
or 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
DELETE
action endpointUse 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
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