Introduction

The Loyalty Coupons API allows you to create loyalty coupons when a customer redeems their loyalty points for loyalty rewards.

With the Loyalty Coupons API, you can:

  • Redeem points for coupons.
  • Redeem points for coupons for the current member.
  • Retrieve information about existing loyalty coupons.
  • Bulk retrieve loyalty coupons.
  • Get coupons for the current member.
  • Query loyalty coupons.
  • Delete loyalty coupons.

Before you begin

It's important to note the following points before starting to code:

  • The site must have Wix Loyalty Program installed.

Terminology

  • Loyalty coupon: A specific loyalty object that holds the specifications used to create a reference coupon.
  • Reference coupon: The actual coupon that is created when loyalty points are redeemed for a loyalty reward. The customer receives the reference coupon, which they can apply to their order.
Did this help?

Coupon Object


A loyalty coupon is created when a customer redeems their loyalty points for a reward. Creating a loyalty coupon also creates a corresponding "reference" coupon with the Coupons API.

Properties
idstringRead-onlyformat GUID

Loyalty coupon ID.


accountIdstringRead-onlyformat GUID

Loyalty account ID of the customer that redeemed points for a coupon.


memberIdDeprecatedstringRead-onlydeprecated - use memberId insteadformat GUID

Member ID of the customer that redeemed points for a coupon.


memberIdstringRead-onlyformat GUID

Member ID of the customer that redeemed points for a coupon.


transactionIdstringRead-onlyformat GUID

Transaction ID for the transaction that created a coupon.


couponReferenceCouponReferenceRead-only

Reference coupon information for the corresponding coupon that is created along with the loyalty coupon.


statusstringRead-only

Loyalty coupon status.

This status relates to the corresponding coupon that is created at the same time as the loyalty coupon and is included in couponReference.


rewardNamestringRead-onlyminLength 1maxLength 50

Name of reward that was redeemed to create this coupon.


revisionintegerformat uint64

Revision number, which increments by 1 each time the loyalty coupon is updated.

To prevent conflicting changes, the current revision must be passed when updating the loyalty coupon.


createdDatestringRead-onlyformat date-time

Date and time the loyalty coupon was created.


updatedDatestringRead-onlyformat date-time

Date and time the loyalty coupon was last updated.

LoyaltyCoupon
JSON
{ "coupon": { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "PENDING", "rewardName": "Free shipping", "revision": "1", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:53.639Z" } }
Did this help?

POST

Redeem Points For Coupon


Redeems a customer's loyalty points for a loyalty reward and creates a loyalty coupon.

Creating a loyalty coupon also creates a corresponding "reference" coupon with the Coupons API. The customer receives the reference coupon, which they can apply to their order. The loyalty coupon and its corresponding reference coupon are linked and the loyalty coupon's status reflects the current state of the reference coupon.

Check which loyalty rewards a site has available with List Rewards.

Endpoint
POST
https://www.wixapis.com/loyalty-coupons/v1/coupons

Body Params
rewardIdstringRequiredformat GUID

ID of the loyalty reward to redeem.


loyaltyAccountIdstringRequiredformat GUID

ID of the loyalty account of the customer redeeming points.

Response Object
couponCoupon

Created loyalty coupon.

Redeem points for coupon
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ --data-raw '{ "rewardId": "960d1ef4-80b8-4c87-8301-cda0c35b6b8d", "loyaltyAccountId": "bf14421a-0ccb-4656-a91f-84119e8fc994" }'
Response
JSON
{ "coupon": { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "PENDING", "rewardName": "Free shipping", "revision": "1", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:53.639Z" } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Redeem Current Member Points For Coupon


Redeems a current customer's loyalty points for a loyalty reward and creates a loyalty coupon.

Creating a loyalty coupon also creates a corresponding "reference" coupon with the Coupons API. The customer receives the reference coupon, which they can apply to their order. The loyalty coupon and its corresponding reference coupon are linked and the loyalty coupon's status reflects the current state of the reference coupon.

Check which loyalty rewards a site has available with List Rewards.

Note: This endpoint requires visitor or member authentication.

Endpoint
POST
https://www.wixapis.com/loyalty-coupons/v1/coupons/redeem-my-coupon

Body Params
rewardIdstringRequiredformat GUID

ID of the loyalty reward to redeem.

Response Object
couponCoupon

Created loyalty coupon.

Redeem current member points for coupon
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons/redeem-my-coupon' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ --data-raw '{ "rewardId": "960d1ef4-80b8-4c87-8301-cda0c35b6b8d" }'
Response
JSON
{ "coupon": { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "PENDING", "rewardName": "Free shipping", "revision": "1", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:53.639Z" } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Loyalty Coupon


Retrieves a loyalty coupon.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-coupons/v1/coupons/{loyaltyCouponId}

Path Params
loyaltyCouponIdstringRequired

ID of the loyalty coupon to retrieve.

Response Object
loyaltyCouponLoyaltyCoupon

Retrieved loyalty coupon.

Get loyalty coupon
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons/c90918b2-e9a5-4147-b4a4-953e235b9ddd' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "coupon": { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "PENDING", "rewardName": "Free shipping", "revision": "1", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:53.639Z" } }
Did this help?

GET

Get Current Member Coupons


Retrieves the loyalty coupons for the currently logged-in member.

Note: This endpoint requires visitor or member authentication.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/loyalty-coupons/v1/coupons/my-coupons

Request
This endpoint does not take any parameters.
Response Object
loyaltyCouponsArray <LoyaltyCoupon>

Retrieved loyalty coupons.

Get current member coupons
Request
cURL
curl -X GET \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons/my-coupons' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "loyaltyCoupons": [ { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "PENDING", "rewardName": "Free shipping", "revision": "1", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:53.639Z" } ] }
Did this help?

POST

Query Loyalty Coupon


Retrieves a list of loyalty coupons, given the provided paging, filtering, and sorting.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/loyalty-coupons/v1/coupons/query

Body Params
queryQueryRequired

Query options.

Response Object
loyaltyCouponsArray <LoyaltyCoupon>

Retrieved loyalty coupons.


metadataMetadata

Metadata.

Query loyalty coupons
Request
cURL
curl -X POST \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons/query' \ -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \ --data-raw '{ "query": { "filter": {"memberId": {"$eq": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b"}} } }'
Response
JSON
{ "loyaltyCoupons": [ { "id": "c90918b2-e9a5-4147-b4a4-953e235b9ddd", "accountId": "bf14421a-0ccb-4656-a91f-84119e8fc994", "memberId": "e64eee9f-ec4e-4c8a-b015-eb3be0b2761b", "transactionId": "aba2ef65-8f70-4113-b4bd-d44338a4e37d", "couponReference": { "couponId": "e48b4b92-3481-40bf-943d-c9324ae3cd6d", "code": "6Q1LC0K4KHSL", "name": "Free shipping", "specification": { "type": "FREE_SHIPPING", "freeShipping": true } }, "status": "ACTIVE", "rewardName": "Free shipping", "revision": "2", "createdDate": "2024-04-18T15:07:53.639Z", "updatedDate": "2024-04-18T15:07:55.426Z" } ], "metadata": { "count": 1, "cursors": {}, "hasNext": false } }
Did this help?

DELETE

Delete Loyalty Coupon


Deletes a loyalty coupon.

The deletion of a loyalty coupon does not impact the functionality of the corresponding coupon itself.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Loyalty
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/loyalty-coupons/v1/coupons/{id}

Path Params
idstringRequired

ID of the loyalty coupon to delete.

Query Params
revisionnumber

Revision number, which increments by 1 each time the loyalty coupon is updated.

To prevent conflicting changes, the current revision must be passed when updating the loyalty coupon.

Response Object
Returns an empty object.
Delete loyalty coupon
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/loyalty-coupons/v1/coupons/c90918b2-e9a5-4147-b4a4-953e235b9ddd?revision=1' \ -H 'Authorization: <AUTH>'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

Coupon Created


Triggered when a loyalty coupon is created.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.coupon.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.loyalty.v1.coupon_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?

Coupon Deleted


Triggered when a loyalty coupon is deleted.

Permissions
Manage Loyalty
Read Loyalty
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.loyalty.v1.coupon.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.loyalty.v1.coupon_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?