--- title: "List Customers" method: GET path: "/v1/customers" tags: ["Customers"] --- # List Customers `GET /v1/customers` Returns a list of customers. ## Query parameters - `limit` integer - `page` integer - `email` string - `city` string - `name` string - `segment_id` string - `created_at[before]` string, date-time - `created_at[after]` string, date-time - `updated_at[before]` string, date-time - `updated_at[after]` string, date-time - `order` 'created_at' | '-created_at' | 'updated_at' | '-updated_at' | 'source_id' | '-source_id' - `starting_after` string, date-time ## Response `200` Returns a dictionary with customer objects. The customers are returned sorted by creation date, with the most recent customers appearing first. - CustomersListResponseBody — Response body schema for **GET** `v1/customers`. - `object` string, required — The type of the object represented by JSON. This object stores information about customers in a dictionary. - `data_ref` string, required — Identifies the name of the attribute that contains the array of customer objects. - `customers` CustomerWithSummaryLoyaltyReferrals[], required — Contains array of customer objects. - `id` string — The ID of an existing customer that will be linked to redemption in this request. - `source_id` string — A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. - `summary` CustomerSummary, required - `redemptions` CustomerSummaryRedemptions, required - `total_redeemed` integer, required — Total number of redemptions made by the customer. - `total_failed` integer, required — Total number of redemptions that failed. - `total_succeeded` integer, required — Total number of redemptions that succeeded. - `total_rolled_back` integer, required — Total number of redemptions that were rolled back for the customer. - `total_rollback_failed` integer, required — Total number of redemption rollbacks that failed. - `total_rollback_succeeded` integer, required — Total number of redemption rollbacks that succeeded. - `gift` object, required — Summary of gift card credits. - `redeemed_amount` integer, required — Total amount of gift card credits redeemed by customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `amount_to_go` integer, required — Remaining gift card balance across all gift cards. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `loyalty_card` object, required — Summary of loyalty points. - `redeemed_points` integer, required — Total number of loyalty points redeemed by the customer. - `points_to_go` integer, required — Sum of remaining available point balance across all loyalty cards. - `orders` CustomerSummaryOrders, required — Lists details about orders related to the customer. Lists only data for orders with the `PAID` or `FULFILLED` status. Data from orders with a `CREATED` or `CANCELED` status are not included. The data is updated also when an order changes status. - `total_amount` integer, required — The total amount spent by the customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `total_count` integer, required — Total number of orders made by the customer. - `average_amount` integer, required — Average amount spent on orders. `total_amount` ÷ `total_count`. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `last_order_amount` integer, required — Amount spent on last order. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `last_order_date` string, date-time — Timestamp representing the date and time of the customer's last order in ISO 8601 format. - `loyalty` CustomerLoyalty, required - `points` integer, required — Customer's loyalty points minus expired for all loyalty cards which the customer has. - `referred_customers` integer, required — Total number of customers referred by the customer. - `campaigns` object, required — Contains campaigns with details about point balances and how many customers were referred by the customer. - `referrals` CustomerReferrals, required — Summary of customer's referrals, in this case, the customer being the referee, i.e. information about the source of referrals and number of times the customer was referred by other customers. - `total` integer, required — Total number of times this customer received a referral, i.e. was referred by another customer. - `campaigns` object[], required — Contains an array of campaigns that served as the source of a referral for the customer. - `campaign_id` string, required — Unique campaign ID, assigned by Voucherify. - `referrer_id` string, required — Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer. - `related_object_id` string, required — Related object id - `related_object_type` string, required — Related object type, i.e. `redemption`. - `date` string, date-time, required — Timestamp representing the date and time when the customer was referred in ISO 8601 format. - `system_metadata` object — Object used to store system metadata information. - `created_at` string, date-time — Timestamp representing the date and time when the customer was created. The value is shown in the ISO 8601 format. - `updated_at` string, date-time — Timestamp representing the date and time when the customer was updated. The value is shown in the ISO 8601 format. - `assets` object — Contains information about the customer's cockpit. ⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center. - `cockpit_url` string — URL address to customer preference center. Previously, a customer's cockpit URL address. - `cockpit_preference_center_url` string — URL address to customer preference center. - `object` 'customer', required — The type of the object represented by JSON. - `name` string — Customer's first and last name. - `description` string — An arbitrary string that you can attach to a customer object. - `email` string — Customer's email address. - `phone` string — Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. - `birthday` string, date — `Deprecated`. ~~Customer's birthdate; format YYYY-MM-DD~~. - `birthdate` string, date — Customer's birthdate; format YYYY-MM-DD. - `address` object, nullable — Customer's address. - `city` string — City - `state` string — State - `line_1` string — First line of address. - `line_2` string — Second line of address. - `country` string — Country. - `postal_code` string — Postal code. - `metadata` object — A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. - `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. --- [API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/revisions/4982266e0494/schema)