Skip to main content
POST
/
v1
/
loyalties
/
{campaignId}
/
members
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/loyalties/{campaignId}/members \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "customer": "source_customer_1",
  "metadata": {
    "year": 2022
  },
  "channel": "postman",
  "voucher": "KpzbHUY5"
}'
{
  "id": "v_0TxKw1bm0oZuS5lwA8526vze1OBMV1OH",
  "code": "KpzbHUY5",
  "campaign": "Loyalty Campaign",
  "campaign_id": "camp_eTIsUtuzkRXQT6rsUQqrS5Gw",
  "category": "New Customers",
  "category_id": "cat_0b6152ce12414820dc",
  "categories": [
    {
      "id": "cat_0b6152ce12414820dc",
      "name": "New Customers",
      "hierarchy": 0,
      "created_at": "2022-07-14T20:17:07.657Z",
      "object": "category"
    }
  ],
  "type": "LOYALTY_CARD",
  "discount": null,
  "gift": null,
  "loyalty_card": {
    "points": 0,
    "balance": 0
  },
  "start_date": null,
  "expiration_date": null,
  "validity_timeframe": null,
  "validity_day_of_week": null,
  "active": true,
  "additional_info": null,
  "metadata": {
    "Season": "Fall"
  },
  "assets": {
    "qr": {
      "id": "U2FsdGVkX1+hdZfzUaz448vIsyf7WpvXiDyqFbyw0+P5wMu12w3B5DyYwA7LCSK+Nr7TA7PKGuHOTGxfBieqrhvJo81HiaIJimDOhk+ecEOisMRmHf6XsNckVlyBHmkpBiXWNm8UDwZnXOAG75Usdw==",
      "url": "{{internalVoucherifyURL}}"
    },
    "barcode": {
      "id": "U2FsdGVkX19VRXApVvZ9/ArwBd0wNg7s2KZBXrFvPXZdDQyzGj0HbbEIx5TAoXNR9zaE5kzIj9BElzgK82aOMMVnc1sqvr93xw+YeYMnqGqHRZfM78pYC8560Zc3U6IELtxzaJJ0x2uDUe6Dc9XYeg==",
      "url": "{{internalVoucherifyURL}}"
    }
  },
  "is_referral_code": false,
  "created_at": "2022-11-21T15:48:57.860Z",
  "updated_at": "2022-11-21T15:49:36.671Z",
  "holder_id": "cust_8KQmHxAERpgebYcFhSpZRr37",
  "redemption": {
    "quantity": null,
    "redeemed_quantity": 0,
    "redeemed_points": 0,
    "object": "list",
    "url": "/v1/vouchers/KpzbHUY5/redemptions?page=1&limit=10"
  },
  "publish": {
    "object": "list",
    "count": 1,
    "url": "/v1/vouchers/KpzbHUY5/publications?page=1&limit=10"
  },
  "object": "voucher"
}

Authorizations

​
X-App-Id
string
header
required
​
X-App-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
campaignId
string
required

Unique campaign ID of the loyalty program.

Example:

"camp_rRsfatlwN7unSeUIJDCYedal"

Body

application/json

Provide details to whom the loyalty card should be assigned.

You can choose to either specify the exact loyalty card code that you want to publish from existin (non-assigned) codes, or choose not to specify a voucher code. If you choose not to specify a code in the request paylaod, then the system will choose the next available voucher code available to be assigned to a customer.

You can also include metadata in the request payload. This metadata will be assigned to the publication object, but will not be returned in the response to this endpoint. To see of publications (assignments of particular codes to customers) and publication metadata, use the <!-- [List Publications](OpenAPI.json/paths/~1publications/get) -->List Publications endpoint.

Request body schema for assigning a loyalty card to a customer using POST /loyalties/{campaignId}/members. Create publication

​
customer
object
required

Contains information about the customer to whom the publication was directed.

​
voucher
string

Code of voucher being published.

​
source_id
string

The merchant's publication ID if it is different from the Voucherify publication ID. It's an optional tracking identifier of a publication. It is really useful in case of an integration between multiple systems. It can be a publication ID from a CRM system, database or 3rd-party service. If source_id is provided only 1 voucher can be published per request.

​
metadata
object

The metadata object stores all custom attributes assigned to the publication. A set of key/value pairs that you can attach to a publication object. It can be useful for storing additional information about the publication in a structured format.

​
channel
string

Specify the distribution channel.

Response

Returns the voucher object that was published to the customer provided in the request payload.

Respone body schema for assigning a loyalty card to a customer using POST /loyalties/{campaignId}/members. This is an object representing a loyalty member.

​
id
string

Assigned by the Voucherify API, identifies the voucher.

Example:

"v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV"

​
code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example:

"WVPblOYX"

​
campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example:

"Loyalty campaign"

​
campaign_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example:

"camp_FNYR4jhqZBM9xTptxDGgeNBV"

​
category
string

Tag defining the category that this voucher belongs to.

​
category_id
string

Unique category ID assigned by Voucherify.

Example:

"cat_0bb343dee3cdb5ec0c"

​
type
enum<string>
default:LOYALTY_CARD

Defines the type of the voucher.

Available options:
LOYALTY_CARD
​
discount
object | null
​
gift
object | null
​
loyalty_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY_CARD. Defaults to null.

​
start_date
string<date-time>

Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is inactive before this date.

Example:

"2021-12-01T00:00:00.000Z"

​
expiration_date
string<date-time>

Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is inactive after this date.

Example:

"2021-12-31T00:00:00.000Z"

​
validity_timeframe
object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

​
validity_day_of_week
enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

  • 0 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 Saturday
​
validity_hours
object

Determines the hours of validity, e.g. to create a happy hours scenario.

​
active
boolean | null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start_date and expiration_date.

  • true indicates an active voucher
  • false indicates an inactive voucher
​
additional_info
string

An optional field to keep any extra textual information about the code such as a code description and details.

​
metadata
object

The metadata object stores all custom attributes assigned to the code. A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format.

​
assets
object

Stores links to images of QR and barcode that correspond to an encrypted voucher code.

​
is_referral_code
boolean | null

This is always false for loyalty members.

​
created_at
string<date-time>

Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

​
updated_at
string<date-time>

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example:

"2021-12-22T10:14:45.316Z"

​
holder_id
string

Unique identifier of the customer who owns the voucher.

Example:

"cust_eWgXlBBiY6THFRJwX45Iakv4"

​
object
string
default:voucher

The type of the object represented by JSON. Default is voucher.

​
publish
object

This object stores a summary of publish events: an events counter and an endpoint which can be called to return details of each event. A publication is required for loyalty cards and referral codes. This object gets updated whenever a voucher has been published. Publication means assigning a code to a particular customer. Typically, a publication is made by distributing your codes to your customers, e.g. through Export to MailChimp or <!-- [publish voucher](OpenAPI.json/paths/~1publications/post) -->publish voucher API method.

<!-- title: My Table Title -->
RequiredOptional
type:LOYALTY_CARDtype:DISCOUNT_VOUCHER
is_referral_code:truetype:GIFT_VOUCHER
​
redemption
object

Stores a summary of redemptions that have been applied to the voucher.

⌘I