List Customers

Retrieve a list of all customers.

You can filter the list with query parameters.

Note

(Sandbox only) A date range that exceeds 90 days, defined with both starting_afterand ending_before, returns ERROR_QUERY_DATE_RANGE_EXCEEDS_90_DAYS.

Parameters

Request Query Parameters

- ending_before
- The ID of the customer created after the last customer you want to retrieve. String starting with cus_.
  (Sandbox only) Date range: 1-90 days. Default: 90 days.
- limit
- The maximum number of customers to return. Range: 1-100.
  10
- starting_after
- The ID of the customer created before the first customer you want to retrieve. String starting with cus_.
  (Sandbox only) Date range: 1-90 days. Default: 90 days.

Request Header Parameters

Response Parameters

- addresses
- Describes the addresses associated with this customer. For details of the fields in the 'address' object, see Create Address.
- birth_country
- Country where the customer was born. Two-letter ISO 3166-1 ALPHA-2 code for the country.
- business_vat_id
- The tax ID number of the customer. Relevant when the customer is a business.
- category
- Category of payment method. One of the following:
  bank_redirect
  bank_transfer
  card
  card_to_card
  cash
  ewallet
  rapyd_ewallet
- coupon
- The ID of a discount coupon that is assigned to this customer. The coupon must use the same currency as the customer's default payment method.
- created_at
- Time of creation of this customer, in Unix time.
- customer
- ID of the customer profile, a string starting with cus_.
- date_of_birth
- Date of birth of the customer. Format: DD/MM/YYYY
- default_payment_method
- The payment method that is used when the payment object or subscription does not specify a payment method. The value must also appear in the payment_methods list. The payment method is referenced by its name field.
- delinquent
- Indicates whether there is currently a failure of an automatic payment that is part of a subscription, or an invoice that was not paid when due.
- description
- A text description of the customer.
- discount
- Contains information about the coupon that applies to the customer.
  To add a discount to a customer, see Update Customer.
- email
- Customer's email address.
- ewallet
- ID of the wallet that is linked to the customer. String starting with ewallet_.
  Each wallet can be associated with only one customer.
- fields
- Contains the fields that are for the specific payment method.
  To determine what fields are required for the payment method, see Get Payment Method Required Fields.
- id
- ID of the customer profile. String starting with cus_.
- invoice_prefix
- A custom string that is prefixed to all invoices for this customer.
- metadata
- A JSON object defined by the client. See Metadata.
- name
- The name of the customer.
- nationality
- The citizenship of the customer. Two-letter ISO 3166-1 ALPHA-2 code for the country.
- next_action
- Indicates the next action for completing the payment. One of the following values:
  3d_verification - The next action is 3DS authentication. Relevant only to card payments.
  pending_capture - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero.
  pending_confirmation - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.
  not_applicable - The payment has completed or the next action is not relevant.
- occupation
- Occupation of the customer.
- payment_methods
- An object containing the following fields:
  data
  A list of up to three payment methods.
  acs_check
  Results of the Access Control Server (ACS) check. Possible values:
  pass
  fail
  unavailable
  unchecked
  Relevant to cards.
  address
  Address of the customer.
  canton
  Name of the canton administrative subdivision, as used in banking.
  city
  City portion of the address.
  country
  The two-letter ISO 3166-1 ALPHA-2 code for the country.
  created_at
  Time of creation of the object, in Unix time.
  district
  Name of the district administrative subdivision, as used in banking.
  id
  ID of the address object.
  line_1
  Line 1 of the address, such as a building number and street name.
  line_2
  Line 2 of the address, such as a suite or apartment number, or the name of a named building.
  line_3
  Line 3 of the address.
  metadata
  A JSON object defined by the client. See Metadata.
  name
  The name of a contact person or an "in care of" person at this address. For a personal wallet contact, alphabetic characters and spaces.
  phone_number
  Phone number associated with this specific address in E.164 format. Must be unique.
  state
  State or province portion of the address.
  zip
  Postal code portion of the address.
  bin_details
  Bank identification details. Includes the following fields:
  bin_number
  BIN number of the bank.
  brand
  The brand of the card. For example, Visa.
  country
  Country of the bank that issued the card.
  type
  The type of the card:
  credit
  debit
  prepaid
  category
  Category of payment method. One of the following:
  bank_redirect
  bank_transfer
  card
  card_to_card
  cash
  ewallet
  rapyd_ewallet
  cvv_check
  Verification of the card’s CVV. Valid values:
  pass
  fail
  unavailable
  unchecked
  fingerprint_token
  Hash of the card number, expiration date and CVV.
  Relevant to cards.
  id
  ID of the Payment Method object. String starting with card_ or other_.
  image
  A URL to the image of the icon for the type of payment method.
  last4
  Last 4 digits of the card.
  Relevant to card payment methods.
  metadata
  A JSON object defined by the client. See Metadata.
  name
  Full name of the customer.
  next_action
  Indicates the next action for completing the payment. One of the following values:
  3d_verification - The next action is 3DS authentication. Relevant only to card payments.
  pending_capture - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero.
  pending_confirmation - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.
  not_applicable - The payment has completed or the next action is not relevant.
  supporting_documentation
  Reserved.
  type
  Name of the payment method type. For example, us_mastercard_card.
  To get a list of payment methods for a country, use List Payment Methods by Country.
  webhook_url
  Reserved.
  has_more
  Indicates whether there are more than three payment methods for this customer.
  total_count
  Total number of payment methods for this customer.
  url
  URL for requesting all of the payment methods for this customer.
- phone_number
- Customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct.
- subscriptions
- Describes the subscriptions associated with this customer. Array of objects. For details of the fields in the 'subscriptions' object, see Create Subscription.

Code Samples

.NET

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/customers?limit=2");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest(
      'GET',
      '/v1/customers?limit=2'
    );

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

PHP

<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', "/v1/customers?limit=2");
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

result = make_request(method='get', path='/v1/customers?limit=2')
pprint(result)

/v1/customers

List Customers

curl -X get
https://sandboxapi.rapyd.net/v1/customers?limit=2
-H 'access_key: your-access-key-here'
-H 'Content-Type: application/json'
-H 'salt: your-random-string-here'
-H 'signature: your-calculated-signature-here'
-H 'timestamp: your-unix-timestamp-here'

{
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "8875eb5d-d43b-461e-acba-b603e26ec134"
  },
  "data": [
    {
      "id": "cus_a97ac31867f1e2e9903fc2cb936241a7",
      "delinquent": false,
      "discount": null,
      "name": "Person Customer",
      "default_payment_method": "",
      "description": "",
      "email": "person.customer.162417@example.com",
      "phone_number": "+14155551237",
      "invoice_prefix": "",
      "addresses": [],
      "payment_methods": null,
      "subscriptions": null,
      "created_at": 1753881860,
      "metadata": {
        "merchant_defined": true
      },
      "business_vat_id": "",
      "ewallet": "ewallet_31fb2dbbaf6519461ee4fbe1062220d3",
      "occupation": "",
      "birth_country": "",
      "date_of_birth": "",
      "nationality": ""
    },
    {
      "id": "cus_f3d4d8575d30b27aa39230e76fb83a54",
      "delinquent": false,
      "discount": null,
      "name": "Company Customer",
      "default_payment_method": "",
      "description": "",
      "email": "company.customer.162417@example.com",
      "phone_number": "+14155551236",
      "invoice_prefix": "",
      "addresses": [],
      "payment_methods": {
        "data": [
          {
            "id": "other_2d1a55ed70548f259f6a488fd81ed96a",
            "type": "pl_p24_bank",
            "category": "bank_redirect",
            "metadata": {
              "merchant_defined": true
            },
            "image": "https://iconslib.rapyd.net/checkout/pl_p24_bank.png",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "bic_swift": "",
            "account_last4": ""
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_f3d4d8575d30b27aa39230e76fb83a54/payment_methods"
      },
      "subscriptions": null,
      "created_at": 1753881859,
      "metadata": {
        "merchant_defined": true
      },
      "business_vat_id": "",
      "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
      "occupation": "",
      "birth_country": "",
      "date_of_birth": "",
      "nationality": ""
    }
  ]
}

In this section:

Documentation