Core Resources

Customers

The Customer object holds account and billing information. Email is unique on the customer; no two customers for a store can have the same email. Address is the child of the customer object. There can be many child addresses on a customer, but only one parent customer per address.

Endpoints

POST/customers
GET/customers/{id}
PUT/customers/{id}
DELETE/customers/{id}
GET/customers
GET/customers/count
GET/customers/{id}/payment_sources

#The customer object

The following fields are deprecated: stripe_customer_token, paypal_customer_token, authorizedotnet_profile_id, authorizedotnet_payment_profile_id. To add payment methods to a customer use 2021-11 /payment_methods instead

Attributes

idinteger
Unique numeric identifier for the customer.
accepts_marketingboolean
Indicates whether the Customer gives consent for marketing communications.
billing_address1string
The customer’s billing address.
billing_address2string
An additional field for the customer’s billing address.
billing_citystring
The customer’s billing city.
billing_companystring
The customer’s billing company.
billing_countrystring
The customer’s billing country.
billing_first_namestring
The customer’s billing first name. Required when creating a customer.
billing_last_namestring
The customer’s billing last name. Required when creating a customer.
billing_phonestring
The customer’s billing phone number.
billing_provincestring
The customer’s billing province or state name.
billing_zipstring
The customer’s billing zip or postal code.
created_atdatetime
The date and time when the customer was created.
emailstring
The email address of the customer.
first_charge_processed_atstring
Date when first charge was processed for the customer.
first_namestring
The customer’s first name.
has_card_error_in_dunningboolean
Does have a credit card in dunning, can be true and false.
has_valid_payment_methodboolean
Is the payment method valid or not, can be true and false.
hashstring
The unique string identifier used in a customers portal link.
last_namestring
The customer’s last name.
number_active_subscriptionsinteger
The number of active subscriptions for the customer.
number_subscriptionsinteger
The number of subscriptions for the customer.
phonestring
The customer's phone number.
processor_typestring
What the merchant processor customer is stored on.
reason_payment_method_not_validstring
Why payment method is not valid.
shopify_customer_idstring
Shopify’s unique identifier for the customer.
statusstring
Customer’s status, can be ACTIVE and INACTIVE.
updated_atdatetime
The date and time when the customer was last updated.

The customer object

{
  "id": 18819267,
  "accepts_marketing": true,
  "analytics_data": {
    "utm_params": []
  },
  "billing_address1": "3030 Nebraska Avenue",
  "billing_address2": null,
  "billing_city": "Los Angeles",
  "billing_company": null,
  "billing_country": "United States",
  "billing_phone": "3103843698",
  "billing_province": "California",
  "billing_zip": "90404",
  "created_at": "2018-11-14T08:40:38",
  "email": "example_mail@gmail.com",
  "first_charge_processed_at": null,
  "first_name": "Jacob",
  "has_card_error_in_dunning": false,
  "has_valid_payment_method": false,
  "hash": "18819267b1f9095be98f13a8",
  "last_name": "Bronowski",
  "number_active_subscriptions": 0,
  "number_subscriptions": 0,
  "phone": "+16175551212",
  "processor_type": null,
  "reason_payment_method_not_valid": null,
  "shopify_customer_id": null,
  "status": "INACTIVE",
  "stripe_customer_token": "cus_I9bJ...",
  "updated_at": "2018-11-14T08:40:38"
}

#Create a customer

POST/customers

CustomRCSSCI

Create a customer in Recharge.

If you plan to add payment information, it must be the tokenized customer representation. We do not accept card data directly. Please make sure it starts with ‘cus’ and not with a 'tok’, as the 'cus’ is prefix for customer token, and 'tok’ is prefix for payment token.

Creating a customer in Recharge will not create the customer on any other platform at this time.

Write_Payments permission is only required when creating customers with payment token information, or updating payment token information on a customer.

Scopeswrite_customerswrite_payments

Body parameters

accepts_marketingboolean
Indicates whether the Customer gives consent for marketing communications.
authorizedotnet_payment_profile_idintegerDeprecated
Authorize.net customer payment profile id. Required when authorizedotnet_profile_id is provided.
authorizedotnet_profile_idintegerDeprecated
Authorize.net customer profile id. If both authorizedotnet_profile_id and authorizedotnet_payment_profile_id is provided the authorize.net payment profile will be tokenized and associated with the created customer. The tokenized value is returned as customer’s authorizedotnet_customer_token field.
billing_address1stringRequired
The customer’s billing address 1.
billing_address2string
An additional field for the customer’s billing address.
billing_citystringRequired
The customer’s billing city.
billing_companystring
The customer’s billing company.
billing_countrystringRequired
The customer’s billing country.
billing_first_namestringRequired
The customer’s billing first name.
billing_last_namestringRequired
The customer’s billing last name.
billing_phonestring
The customer’s billing phone number.
billing_provincestringRequired
The customer’s billing province or state name.
billing_zipstringRequired
The customer’s billing zip or postal code.
emailstringRequired
The customer’s email address.
first_namestringRequired
The customer’s first name.
last_namestringRequired
The customer’s last name.
paypal_customer_tokenstringDeprecated
The payment processor customer payment token.
phonestring
The customer's phone number.
processor_typestring
What the merchant processor customer is stored on.
shopify_customer_idstring
The shopify customer id.
_The provided "shopify_customer_id" must match the provided "email" in the Shopify database for the customer.
stripe_customer_tokenstringDeprecated
The customer token, you will need to tokenize customers first on the payment processors end, and after you get the customer token, you can create the Recharge customer with it.

POST/customers

curl -X POST 'https://api.rechargeapps.com/customers' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "billing_address1": "3030 Nebraska Avenue",
  "billing_city": "Los Angeles",
  "billing_country": "United States",
  "billing_first_name": "Mike",
  "billing_last_name": "Flynn",
  "billing_phone": "3103843698",
  "billing_province": "California",
  "billing_zip": "90404",
  "email": "example_mail@gmail.com",
  "first_name": "Mike",
  "last_name": "Flynn",
  "stripe_customer_token": "Customer_payment_token"
}'

Response

{
  "customer": {
    "id": 18819267,
    "accepts_marketing": true,
    "analytics_data": {
      "utm_params": []
    },
    "billing_address1": "3030 Nebraska Avenue",
    "billing_address2": null,
    "billing_city": "Los Angeles",
    "billing_company": null,
    "billing_country": "United States",
    "billing_phone": "3103843698",
    "billing_province": "California",
    "billing_zip": "90404",
    "created_at": "2018-11-14T08:40:38",
    "email": "example_mail@gmail.com",
    "first_charge_processed_at": null,
    "first_name": "Mike",
    "hash": "18819267b1f9095be98f13a8",
    "has_card_error_in_dunning": false,
    "has_valid_payment_method": false,
    "last_name": "Flynn",
    "number_active_subscriptions": 0,
    "number_subscriptions": 0,
    "phone": "+16175551212",
    "processor_type": null,
    "reason_payment_method_not_valid": null,
    "shopify_customer_id": null,
    "status": "INACTIVE",
    "stripe_customer_token": "cus_I9bJ...",
    "updated_at": "2018-11-14T08:40:38"
  }
}

#Retrieve a customer

GET/customers/{id}

Retrieve one customer using the Recharge customer id.

Scoperead_customers

GET/customers/{id}

curl 'https://api.rechargeapps.com/customers/18819267' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "customer": {
    "id": 18819267,
    "accepts_marketing": true,
    "analytics_data": {
      "utm_params": []
    },
    "billing_address1": "3030 Nebraska Avenue",
    "billing_address2": null,
    "billing_city": "Los Angeles",
    "billing_company": null,
    "billing_country": "United States",
    "billing_phone": "3103843698",
    "billing_province": "California",
    "billing_zip": "90404",
    "created_at": "2018-11-14T08:40:38",
    "email": "example_mail@gmail.com",
    "first_charge_processed_at": null,
    "first_name": "Mike",
    "hash": "18819267b1f9095be98f13a8",
    "has_card_error_in_dunning": false,
    "has_valid_payment_method": false,
    "last_name": "Flynn",
    "number_active_subscriptions": 0,
    "number_subscriptions": 0,
    "phone": "+16175551212",
    "processor_type": null,
    "reason_payment_method_not_valid": null,
    "shopify_customer_id": null,
    "status": "INACTIVE",
    "stripe_customer_token": "cus_I9bJ...",
    "updated_at": "2018-11-14T08:40:38"
  }
}

#Update a customer

PUT/customers/{id}

Modify an existing customer to match the specified parameters.

Note: For US citizens parameter billing_zip is required when updating customer’s billing_country parameter

Scopewrite_customers

Body parameters

accepts_marketingboolean
Indicates whether the Customer gives consent for marketing communications.
emailstring
Email address of the customer.
billing_address1string
Customer’s billing address 1.
billing_address2string
An additional field for the customer’s billing address.
billing_citystring
Customer’s billing city.
billing_companystring
An additional field for the customer’s company.
billing_countrystring
Customer’s billing country.
billing_first_namestring
Customer’s billing first name.
billing_last_namestring
Customer’s billing last name.
billing_phonestring
Customers billing phone number.
billing_provincestring
Customer’s billing province or state name.
billing_zipstring
Customer’s billing zip or postal code.
first_namestring
Customer’s first name.
last_namestring
Customer’s last name.
phonestring
The customer's phone number.
shopify_customer_idinteger
Shopify’s customer id.

PUT/customers/{id}

curl -X PUT 'https://api.rechargeapps.com/customers/18819267' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "billing_address1": "3030 Nebraska Avenue"
}'

Response

{
  "customer": {
    "id": 18819267,
    "accepts_marketing": true,
    "analytics_data": {
      "utm_params": []
    },
    "billing_address1": "3030 Nebraska Avenue",
    "billing_address2": null,
    "billing_city": "Los Angeles",
    "billing_company": null,
    "billing_country": "United States",
    "billing_phone": "3103843698",
    "billing_province": "California",
    "billing_zip": "90404",
    "created_at": "2018-11-14T08:40:38",
    "email": "example_mail@gmail.com",
    "first_charge_processed_at": null,
    "first_name": "Mike",
    "hash": "18819267b1f9095be98f13a8",
    "has_card_error_in_dunning": false,
    "has_valid_payment_method": false,
    "last_name": "Flynn",
    "number_active_subscriptions": 0,
    "number_subscriptions": 0,
    "phone": "+16175551212",
    "processor_type": null,
    "reason_payment_method_not_valid": null,
    "shopify_customer_id": null,
    "status": "INACTIVE",
    "stripe_customer_token": "cus_I9bJ...",
    "updated_at": "2018-11-14T08:40:38"
  }
}

#Delete a customer

DELETE/customers/{id}

Customer deletion will automatically cancel and delete all child Address, Subscription, Onetime, etc. resources of that customer to eliminate orphaned child data.

To delete a certain address without deleting the customer you can use the Delete Address endpoint.

Scopewrite_customers

DELETE/customers/{id}

curl -X DELETE 'https://api.rechargeapps.com/customers/18819267' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}

#List customers

GET/customers

Return a list of customers in your store.

## HTTP request examples

GET /customers
GET /customers?email=example@email.com
GET /customers?hash=143806234a9ff87a8d9e
GET /customers?limit=250
GET /customers?page=2
GET /customers?shopify_customer_id=98273498

Scoperead_customers

Query parameters

emailstring
Returns the user linked to the email address provided.
created_at_maxstring
Gets all customers created before this date.
created_at_minstring
Gets all customers created after this date.
hashstring
Returns the user linked to the given recharge customer hash.
idsstring
Filter customers by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
limitstring
Number of results.
Default value is 50, maximum is 250.
Default 50Maximum 250
pagestringDeprecated
Page to show. Default value is 1.
Default 1
Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
shopify_customer_idstring
Returns the user linked to the given shopify_customer_id.
statusstring
Returns users with specified status
Values are 'ACTIVE’, and 'INACTIVE’.
updated_at_maxstring
Gets all customers updated before this date.
updated_at_minstring
Gets all customers updated after this date.

GET/customers

curl 'https://api.rechargeapps.com/customers?limit=3' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "customers": [
    {
      "id": 18819267,
      "accepts_marketing": true,
      "analytics_data": {
        "utm_params": [
          {
            "utm_campaign": "spring_sale",
            "utm_content": "differentiate-content",
            "utm_data_source": "website_cookie",
            "utm_medium": "email",
            "utm_source": "newsletter",
            "utm_term": "test-term",
            "utm_time_stamp": "2019-12-16T23:57:28.752Z"
          }
        ]
      },
      "billing_address1": "3030 Nebraska Avenue",
      "billing_address2": null,
      "billing_city": "Los Angeles",
      "billing_company": null,
      "billing_country": "United States",
      "billing_phone": "3103843698",
      "billing_province": "California",
      "billing_zip": "90404",
      "created_at": "2018-11-14T08:40:38",
      "email": "example_mail@gmail.com",
      "first_charge_processed_at": null,
      "first_name": "Mike",
      "hash": "18819267b1f9095be98f13a8",
      "has_card_error_in_dunning": false,
      "has_valid_payment_method": true,
      "last_name": "Flynn",
      "number_active_subscriptions": 0,
      "number_subscriptions": 0,
      "reason_payment_method_not_valid": null,
      "shopify_customer_id": null,
      "phone": "+16175551212",
      "processor_type": null,
      "status": "INACTIVE",
      "stripe_customer_token": "cus_I9bJ...",
      "updated_at": "2018-11-14T08:40:38"
    }
  ]
}

#Count customers

GET/customers/count

Retrieve a count of customers.

## HTTP request examples

GET /customers/count
GET /customers/count?created_at_max=2019-11-11
GET /customers/count?created_at_min=2019-11-11
GET /customers/count?created_at_min=2019-11-10&updated_at_max=2019-11-11&status=ACTIVE
GET /customers/count?status=ACTIVE
GET /customers/count?updated_at_max=2019-11-11
GET /customers/count?updated_at_min=2019-11-11

Scoperead_customers

Query parameters

created_at_maxstring
Gets count of all customers created before this date.
created_at_minstring
Gets count of all customers created after this date.
statusstring
Returns the count of users with the specified status
Values are 'ACTIVE’, and 'INACTIVE’.
updated_at_maxstring
Gets count of all customers updated before this date.
updated_at_minstring
Gets count of all customers updated after this date.

Response attributes

countinteger

GET/customers/count

curl 'https://api.rechargeapps.com/customers/count' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "count": 12057
}

#Payment sources

GET/customers/{id}/payment_sources

BigCommerceCustomRCS

Retrieve payment sources for customer

Scoperead_customers

This endpoint has been deprecated. Use 2021-01 /payment_methods instead

Query parameters

cardholder_namestring
Identifies the owner of the credit card.
card_brandstring
Identifies the brand of the credit card.
card_exp_monthstring
The month when the card expires.
card_exp_yearstring
The year when the card expires.
card_last4string
The last four digits of the card.
customer_idstring
Unique customer identifier.
has_card_error_in_dunningstring
If it has true value, then there was an error in the dunning process. There were no errors in the dunning process if it has false value.
payment_typestringDeprecated
Identifies the payment type. It could have credit, debit, paypal or apple_pay values.
processor_namestring
Identifies the payment processor. It could have stripe, braintree or authorize value.
statusstring
Identifies the status of the payment method. It could have active or failed value.
status_reasonstring
Provides more information on why the payment method is not valid if status has failed value.

Response attributes

billing_addressobject
cardholder_namestring
card_brandstring
card_exp_monthstring
card_exp_yearstring
card_last4string
customer_idstring
has_card_error_in_dunningstring
payment_tokenstring
payment_typestring
processor_namestring
statusstring
status_reasonstring

GET/customers/{id}/payment_sources

curl 'https://api.rechargeapps.com/customers/18819267/payment_sources' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "payment_sources": [
    {
      "billing_address": {
        "id": 1,
        "address1": "3030 Nebraska Avenue",
        "address2": null,
        "city": "Los Angeles",
        "company": null,
        "country": "United States",
        "first_name": "Mike",
        "last_name": "Flynn",
        "phone": "3103843698",
        "province": "California",
        "zip": "90404"
      },
      "cardholder_name": null,
      "card_brand": null,
      "card_exp_month": null,
      "card_exp_year": null,
      "card_last4": null,
      "customer_id": 18819267,
      "has_card_error_in_dunning": false,
      "payment_token": "cus_I9bJ...",
      "payment_type": "credit",
      "processor_name": "stripe",
      "status": "active",
      "status_reason": null
    }
  ]
}