logo

Customers

Customers are your customers, sometimes known as accounts, clients, members, patrons, or players in other systems.

Retrieve a list of customers

Retrieve a list of customers.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of Customers was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object (CustomerLifetimeRevenue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Whether the customer has fulfilled a KYC request by providing valid identity and address documents.

Array of SelfLink (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/customers
Request samples
$customers = $client->customers()->search([
    'filter' => 'firstName:John',
]);
Response samples
application/json
[
  • {
    }
]

Create a customer (without an ID)

Create a customer without a predefined ID. The customer's primary address will be used as the default address for payment instruments, subscriptions and invoices if none are provided.

If you wish to create the customer with a predefined ID (which we recommend to prevent duplication), you may use our PUT request described below.

For more information, see preventing duplicates.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Customer resource.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

paymentToken
string

A write-only payment token; if supplied, it will be converted into a payment instrument and be set as the defaultPaymentInstrument. The value of this property will override the defaultPaymentInstrument in the case that both are supplied. The token may only be used once before it is expired.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

Responses
201

Customer.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object (CustomerLifetimeRevenue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Whether the customer has fulfilled a KYC request by providing valid identity and address documents.

Array of SelfLink (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

post/customers
Request samples
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "paymentToken": "string",
  • "defaultPaymentInstrument": {
    },
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "isEddRequired": false
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "email": "user@example.com",
  • "firstName": "string",
  • "lastName": "string",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "defaultPaymentInstrument": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "averageValue": {
    },
  • "paymentCount": 0,
  • "lastPaymentTime": "2019-08-24T14:15:22Z",
  • "lifetimeRevenue": {
    },
  • "invoiceCount": 0,
  • "tags": [
    ],
  • "revision": 0,
  • "isEddRequired": false,
  • "hasFulfilledKyc": true,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve a customer

Retrieve a customer with specified identifier string.

SecuritySecretApiKey or JWT or ApplicationJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

Responses
200

Customer was retrieved successfully.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object (CustomerLifetimeRevenue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Whether the customer has fulfilled a KYC request by providing valid identity and address documents.

Array of SelfLink (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/customers/{id}
Request samples
$customers = $client->customers()->load('myCustomerId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "email": "user@example.com",
  • "firstName": "string",
  • "lastName": "string",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "defaultPaymentInstrument": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "averageValue": {
    },
  • "paymentCount": 0,
  • "lastPaymentTime": "2019-08-24T14:15:22Z",
  • "lifetimeRevenue": {
    },
  • "invoiceCount": 0,
  • "tags": [
    ],
  • "revision": 0,
  • "isEddRequired": false,
  • "hasFulfilledKyc": true,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Upsert a customer with predefined ID

Create or update (upsert) a customer with predefined identifier string. For more information, see preventing duplicates.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Customer resource.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

paymentToken
string

A write-only payment token; if supplied, it will be converted into a payment instrument and be set as the defaultPaymentInstrument. The value of this property will override the defaultPaymentInstrument in the case that both are supplied. The token may only be used once before it is expired.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

Responses
200

Customer.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object (CustomerLifetimeRevenue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Whether the customer has fulfilled a KYC request by providing valid identity and address documents.

Array of SelfLink (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
201

Customer.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

email
string <email>

The customer's email.

firstName
string

The customer's first name.

lastName
string

The customer's last name.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrument)
Any of:

Vaulted payment instrument.

method
required
string

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 158 more
paymentInstrumentId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (ContactObject)
firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object (CustomerAverageValue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Average approved payment amount in Merchant's reporting currency.

amountUsd
number <double>

Average approved payment amount in USD.

paymentCount
integer

The number of approved payments for the customer.

lastPaymentTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object (CustomerLifetimeRevenue)
currency
string 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>

Revenue amount in Merchant's reporting currency.

amountUsd
number <double>

Revenue amount in USD.

invoiceCount
integer

An auto-incrementing number based on the sequence of invoices. If set to 0, then this record is a Lead, otherwise is a Customer.

Array of objects (Tag)

A list of customer's tags.

Array
name
required
string <= 255 characters ^[@~\-\.\w\s]+$

The tag is unique name, which is case-insensitive.

type
required
string

The tag type. Tags of a specific type could only be used for the corresponding entity.

Enum: "customer" "kyc-document"
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) non-empty

The links related to resource.

revision
integer

The number of times the customer data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

isEddRequired
boolean
Default: false

Indicates if EDD is enabled for this customer.

hasFulfilledKyc
boolean

Whether the customer has fulfilled a KYC request by providing valid identity and address documents.

Array of SelfLink (object) or DefaultPaymentInstrumentLink (object) or LeadSourceLink (object) or WebsiteLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of LeadSourceEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

Lead Source object.

object (LeadSource)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

put/customers/{id}
Request samples
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "paymentToken": "string",
  • "defaultPaymentInstrument": {
    },
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "isEddRequired": false
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "email": "user@example.com",
  • "firstName": "string",
  • "lastName": "string",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "defaultPaymentInstrument": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "primaryAddress": {
    },
  • "averageValue": {
    },
  • "paymentCount": 0,
  • "lastPaymentTime": "2019-08-24T14:15:22Z",
  • "lifetimeRevenue": {
    },
  • "invoiceCount": 0,
  • "tags": [
    ],
  • "revision": 0,
  • "isEddRequired": false,
  • "hasFulfilledKyc": true,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Merge and delete a customer

Merge one duplicate customer to another target customer and delete the. former.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
targetCustomerId
required
string

The customer identifier to get the data of the deleted duplicate customer.

Responses
204

Customer has been merged and removed.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

delete/customers/{id}
Request samples
curl -i -X DELETE \
  'https://api-sandbox.rebilly.com/organizations/unknown/customers/{id}?targetCustomerId=string' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "status": 401,
  • "type": "http://example.com",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Retrieve a customer's Lead Source

Retrieve a Lead Source of given customer.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Lead Source was retrieved successfully.

Response Schema: application/json
medium
string

Lead source medium (eg search, display).

source
string

Lead source origin (eg google, yahoo).

campaign
string

Lead source campaign (eg go-big-123).

term
string

Lead source term (eg salt shakers).

content
string

Lead source content (eg smiley faces).

affiliate
string

Lead source affiliate (eg 123, Bob Smith).

subAffiliate
string

Lead source sub-affiliate also called a sub-id or click id in some circles (eg 123456).

salesAgent
string

Lead source sales agent (eg James Bond).

clickId
string

Lead source click id (may come from an ad server).

path
string

Lead source path url (eg www.example.com/some/landing/path).

referrer
string

Lead source referer url as determined (eg www.example.com/some/landing/path).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

original
object Recursive
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/customers/{id}/lead-source
Request samples
$customer = $client->customers()->load('myCustomerId');
$leadSource = $customer->getLeadSource();
Response samples
application/json
{
  • "medium": "string",
  • "source": "string",
  • "campaign": "string",
  • "term": "string",
  • "content": "string",
  • "affiliate": "string",
  • "subAffiliate": "string",
  • "salesAgent": "string",
  • "clickId": "string",
  • "path": "string",
  • "referrer": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "original": {
    }
}

Create a Lead Source for a customer

Create a Lead Source for a customer.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Lead Source resource.

medium
string

Lead source medium (eg search, display).

source
string

Lead source origin (eg google, yahoo).

campaign
string

Lead source campaign (eg go-big-123).

term
string

Lead source term (eg salt shakers).

content
string

Lead source content (eg smiley faces).

affiliate
string

Lead source affiliate (eg 123, Bob Smith).

subAffiliate
string

Lead source sub-affiliate also called a sub-id or click id in some circles (eg 123456).

salesAgent
string

Lead source sales agent (eg James Bond).

clickId
string

Lead source click id (may come from an ad server).

path
string

Lead source path url (eg www.example.com/some/landing/path).

referrer
string

Lead source referer url as determined (eg www.example.com/some/landing/path).

Responses
201

Lead Source was created.

Response Schema: application/json
medium
string

Lead source medium (eg search, display).

source
string

Lead source origin (eg google, yahoo).

campaign
string

Lead source campaign (eg go-big-123).

term
string

Lead source term (eg salt shakers).

content
string

Lead source content (eg smiley faces).

affiliate
string

Lead source affiliate (eg 123, Bob Smith).

subAffiliate
string

Lead source sub-affiliate also called a sub-id or click id in some circles (eg 123456).

salesAgent
string

Lead source sales agent (eg James Bond).

clickId
string

Lead source click id (may come from an ad server).

path
string

Lead source path url (eg www.example.com/some/landing/path).

referrer
string

Lead source referer url as determined (eg www.example.com/some/landing/path).

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

original
object Recursive
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

put/customers/{id}/lead-source
Request samples
application/json
{
  • "medium": "string",
  • "source": "string",
  • "campaign": "string",
  • "term": "string",
  • "content": "string",
  • "affiliate": "string",
  • "subAffiliate": "string",
  • "salesAgent": "string",
  • "clickId": "string",
  • "path": "string",
  • "referrer": "string"
}
Response samples
application/json
{
  • "medium": "string",
  • "source": "string",
  • "campaign": "string",