List Customers

Returns a list of customers.

GET /v1/customers

List Customers

cURL

curl --request GET \
  --url https://{cluster}.voucherify.io/v1/customers \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>'

200

{
  "object": "list",
  "data_ref": "customers",
  "customers": [
    {
      "id": "cust_CSnYd37MXmrbS19XCrghjBsv",
      "source_id": "source_123",
      "name": "Bob Smith",
      "description": "A frequent customer",
      "email": "[e-mail]",
      "phone": "[phone]",
      "birthdate": "2022-01-01",
      "address": {
        "city": "New York",
        "state": "NY",
        "line_1": "123 Main St.",
        "line_2": "APT 3 BLG 5",
        "country": "United States",
        "postal_code": "10001"
      },
      "summary": {
        "redemptions": {
          "total_redeemed": 1,
          "total_failed": 0,
          "total_succeeded": 1,
          "total_rolled_back": 0,
          "total_rollback_failed": 0,
          "total_rollback_succeeded": 0,
          "gift": {
            "redeemed_amount": 0,
            "amount_to_go": 0
          },
          "loyalty_card": {
            "redeemed_points": 0,
            "points_to_go": 4200
          }
        },
        "orders": {
          "total_amount": 1600,
          "total_count": 1,
          "average_amount": 1600,
          "last_order_amount": 1600,
          "last_order_date": "2022-08-30T10:17:39.220Z"
        }
      },
      "loyalty": {
        "points": 2200,
        "referred_customers": 0,
        "campaigns": {
          "Christmas Campaign": {
            "points": 1000,
            "referred_customers": 0
          },
          "Fall Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Winter Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Summer Campaign": {
            "points": 50,
            "referred_customers": 0
          },
          "Spring Campaign": {
            "points": 1000,
            "referred_customers": 0
          }
        }
      },
      "referrals": {
        "total": 1,
        "campaigns": [
          {
            "campaign_id": "camp_rRsfatlwN7unSeUIJDCYedal",
            "referrer_id": "cust_sehkNIi8Uq2qQuRqSr7xn4Zi",
            "related_object_id": "r_0b9d4c5121d64dd01d",
            "related_object_type": "redemption",
            "date": "2022-08-30T10:17:41.089Z"
          }
        ]
      },
      "metadata": {
        "lang": "en",
        "test": true
      },
      "system_metadata": {},
      "created_at": "2022-08-30T06:32:07.380Z",
      "updated_at": "2022-08-30T10:17:58.049Z",
      "object": "customer"
    },
    {
      "id": "cust_X0hU04x7FeisPnD5lctZcQkI",
      "source_id": "[e-mail]",
      "name": "Jane Smith",
      "description": "A nice customer",
      "email": "[e-mail]",
      "phone": "[phone]",
      "birthdate": "2022-01-02",
      "address": {
        "city": "New Yorke",
        "state": "NY",
        "line_1": "123 Main Ste.",
        "line_2": "APT 3 BLG 4e",
        "country": "United Statese",
        "postal_code": "10001e"
      },
      "summary": {
        "redemptions": {
          "total_redeemed": 4,
          "total_failed": 0,
          "total_succeeded": 4,
          "total_rolled_back": 1,
          "total_rollback_failed": 0,
          "total_rollback_succeeded": 1,
          "gift": {
            "redeemed_amount": 0,
            "amount_to_go": 0
          },
          "loyalty_card": {
            "redeemed_points": 0,
            "points_to_go": 15549
          }
        },
        "orders": {
          "total_amount": 210000,
          "total_count": 3,
          "average_amount": 70000,
          "last_order_amount": 70000,
          "last_order_date": "2022-08-30T11:51:08.029Z"
        }
      },
      "loyalty": {
        "points": 15399,
        "referred_customers": 0,
        "campaigns": {
          "Christmas Campaign": {
            "points": 7000,
            "referred_customers": 0
          },
          "Fall Campaign": {
            "points": 2299,
            "referred_customers": 0
          },
          "Winter Campaign": {
            "points": 25,
            "referred_customers": 0
          },
          "Summer Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Spring Campaign": {
            "points": 6000,
            "referred_customers": 0
          }
        }
      },
      "referrals": {
        "total": 2,
        "campaigns": [
          {
            "campaign_id": "camp_rRsfatlwN7unSeUIJDCYedal",
            "referrer_id": "cust_sehkNIi8Uq2qQuRqSr7xn4Zi",
            "related_object_id": "r_0b9d4cc4aa164dd073",
            "related_object_type": "redemption",
            "date": "2022-08-30T10:19:39.196Z"
          },
          {
            "campaign_id": "camp_YDsFdX8TgFtT0RUuKEFyhqs3",
            "referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
            "related_object_id": "r_0b9d61b6484ead0324",
            "related_object_type": "redemption",
            "date": "2022-08-30T11:51:10.445Z"
          }
        ]
      },
      "metadata": {
        "lang": "en",
        "test": false
      },
      "system_metadata": {},
      "created_at": "2022-08-09T09:50:53.620Z",
      "updated_at": "2022-08-30T11:51:24.327Z",
      "object": "customer"
    }
  ],
  "total": 2
}

Authorizations

X-App-Id & X-App-TokenX-Voucherify-OAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Query Parameters

limit · integer

Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items.

Required range: 1 <= x <= 100

page · integer

Which page of results to return. The lowest value is 1, the highest value is 99.

Required range: 1 <= x <= 99

email · string

Limit the customers to the ones that have this specific email address.

city · string

Limit the customers to the ones that are located in the specified city.

name · string

Filter customers by the name property.

segment_id · string

Filter customers by the segment ID.

Warning: Passing additional query parameter filters that are in conflict with the segment filters may return unexpected results.

created_at[before] · string<date-time>

Filter customers by date customer was created.

Example:

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

created_at[after] · string<date-time>

Filter customers by date customer was created.

Example:

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

updated_at[before] · string<date-time>

Filter customers by date customer was updated last time.

Example:

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

updated_at[after] · string<date-time>

Filter customers by date customer was updated last time.

Example:

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

order · enum<string>

This is a property that controls the sorting direction of the results. Sort the results using one of the filtering options, where the dash - preceding a sorting option means sorting in a descending order.

Available options: created_at, -created_at, updated_at, -updated_at, source_id, -source_id

starting_after · string<date-time>

A cursor for pagination. This is a date-time value that defines your place in the list based on created_at property from the customer object. For instance, if you make a list request and receive 100 objects, ending with an object created at 2020-05-24T13:43:09.024Z, your subsequent call can include starting_after=2020-05-24T13:43:09.024Z in order to fetch the next page of the list.

Option	Format	Sorting
Return customers before a specific creation date	- set starting_after parameter to the breakpoint date	Sorting order is descending; the most recent dates first and least recent dates last.
Return customers after a specific create or update date	- include the order parameter set to created_at or updated_at - set starting_after to the breakpoint date	Sorting order is ascending; the least recent dates first and the most recent dates last.

Example:

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

Response

200 - application/json

Returns a dictionary with customer objects. The customers are returned sorted by creation date, with the most recent customers appearing first.

Response body schema for GET v1/customers.

object · string · default: list · required

The type of the object represented by JSON. This object stores information about customers in a dictionary.

data_ref · string · default: customers · required

Identifies the name of the attribute that contains the array of customer objects.

customers · Customer With Summary Loyalty Referrals · object[] · required

Contains array of customer objects.

Show child attributes

total · integer · required

Total number of customers.

has_more · boolean

As query results are always limited (by the limit parameter), the has_more flag indicates if there are more records for given filter parameters. This lets you know if you can run another request (with a different end date filter) to get more records returned in the results.