/
Upsert a customer

Upsert a customer

Request

Creates or updates (upserts) a customer with a specified ID.

If the customer already has an identifier within your system, and you want to create a customer with a specified ID — use this operation to prevent duplicate customers. For more information, see Prevent duplicate customers.

Security
SecretApiKey or JWT
Path
idstring, <= 50 characters^[@~\-\.\w]+$required

ID of the resource.

Bodyapplication/jsonrequired

Customer resource.

websiteIdstring, <= 50 characters(WebsiteId)

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
paymentTokenstringwrite-only

Write-only payment token. If supplied, the token is converted into a payment instrument, and its ID is assigned to defaultPaymentInstrumentId value. The value of this property overrides the defaultPaymentInstrumentId if both are supplied. This token may only be used once before it expires.

defaultPaymentInstrumentIdstring or null, <= 50 characterswrite-only

ID of the customer's default payment instrument.

The default payment instrument is used to automatically pay subscription renewals, and for transaction requests where a specific payment instrument is not provided.

Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
preferredPayoutInstrumentIdstring or null, <= 50 characters

ID of the customer's preferred payment instrument for payouts.

Default:null
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
customFieldsobject(ResourceCustomFields)

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

Default:{}
Example:
{
  "foo": "bar"
}
primaryAddressContactObject (object) or null
One of:

Contact's information.

localestring or null

Language locale identifier in RFC 5646 format.

Default:null
Example:"fr-FR"
taxNumbersArray of objects or null(TaxNumber)

Tax numbers of the customer.

leadSourceobject(LeadSourceData)write-only

Lead source information.

personIdstring or null, <= 50 characters

ID of the associated person.

Example:"prs_0YV7DDSDD1C8DA64KHH2W33CPF"
notificationEmailsArray of strings, (email)

Email addresses for notification delivery in event-based email notifications. When you configure event-based email notifications, you can send to these addresses, the customer's primary email address, or another email address you specify. For more information, see Manage notification emails.

curl -i -X PUT \
  'https://www.rebilly.com/_mock/catalog/all/customers/{id}' \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
    "paymentToken": "string",
    "defaultPaymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
    "preferredPayoutInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
    "customFields": {
      "foo": "bar"
    },
    "primaryAddress": {
      "firstName": "Benjamin",
      "lastName": "Franklin",
      "organization": "Rebilly",
      "address": "36 Craven St",
      "address2": "string",
      "city": "Austin",
      "region": "Texas",
      "country": "GB",
      "postalCode": "WC2N 5NF",
      "phoneNumbers": [
        {
          "label": "main",
          "value": "1-512-777-0269",
          "primary": true
        }
      ],
      "emails": [
        {
          "label": "main",
          "value": "rebilly@example.com",
          "primary": true
        }
      ],
      "dob": "1980-04-01",
      "jobTitle": "CEO"
    },
    "locale": "fr-FR",
    "taxNumbers": [
      {
        "type": "eu-vat",
        "value": "GB980780684",
        "isDefault": true
      }
    ],
    "leadSource": {
      "medium": "string",
      "source": "string",
      "campaign": "string",
      "term": "string",
      "content": "string",
      "affiliate": "string",
      "subAffiliate": "string",
      "salesAgent": "string",
      "clickId": "string",
      "path": "string",
      "referrer": "https://www.rebilly.com"
    },
    "personId": "prs_0YV7DDSDD1C8DA64KHH2W33CPF",
    "notificationEmails": [
      "user@example.com"
    ]
  }'

Responses

Customer.

Bodyapplication/json
idstring, <= 50 charactersread-only

ID of the customer.

Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
emailstring or null, (email)read-only

Customer's email address.

firstNamestring or nullread-only

Customer's first name.

lastNamestring or nullread-only

Customer's last name.

websiteIdstring, <= 50 characters(WebsiteId)

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
defaultPaymentInstrumentobject or nullread-only

Default payment instrument of the customer.

The default payment instrument is used to automatically pay subscription renewals, and for transaction requests where a specific payment instrument is not provided.

preferredPayoutInstrumentIdstring or null, <= 50 characters

ID of the customer's preferred payment instrument for payouts.

Default:null
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

customFieldsobject(ResourceCustomFields)

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

Default:{}
Example:
{
  "foo": "bar"
}
primaryAddressContactObject (object) or null
One of:

Contact's information.

companyobject or null(Company)read-only

Company information that is associated with the customer's primary email address domain.

This is a paid feature, to enable it contact Rebilly.

averageValueobject(CustomerAverageValue)read-only

Average customer value.

paymentCountintegerread-only

Total number of approved payments made by the customer. Payments are the result of sale or capture transactions.

lastPaymentTimestring or null, (date-time)read-only

Date and time when the customer made their last approved payment. Payments are the result of sale or capture transactions.

lifetimeRevenueobject(CustomerLifetimeRevenue)read-only

Customer's lifetime revenue.

invoiceCountintegerread-only

Total number of invoices issued to the customer. This value is auto-incrementing. If this value is 0, the record relates to a lead. A lead is a customer who has not made a payment yet. If this value is greater than or equal to 1 the record relates to a customer.

tagsArray of objects(Tag)read-only

List of customer tags.

revisionintegerread-only

Number of times the customer's data has been modified.

Use this value when analyzing webhook data to determine if a change must take precedence over the current representation.

hasFulfilledKycbooleanread-only

Specifies if the customer has accepted and reviewed identity and address documents, or an accepted credit file document.

organizationIdstring, <= 50 characters(OrganizationId)read-only

Unique organization identifier. An organization is an entity that represents a company. For more information, see Obtain an organization ID.

Example:"org_0YVDM8RC7GDADADSBSMW124JA8"
localestring or null

Language locale identifier in RFC 5646 format.

Default:null
Example:"fr-FR"
taxNumbersArray of objects or null(TaxNumber)

Tax numbers of the customer.

personIdstring or null, <= 50 characters

ID of the associated person.

Example:"prs_0YV7DDSDD1C8DA64KHH2W33CPF"
notificationEmailsArray of strings, (email)

Email addresses for notification delivery in event-based email notifications. When you configure event-based email notifications, you can send to these addresses, the customer's primary email address, or another email address you specify. For more information, see Manage notification emails.

_embeddedobjectread-only

Embedded objects that are requested using the expand query string parameter.

Response
{
  "id": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "email": "user@example.com",
  "firstName": "string",
  "lastName": "string",
  "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  "defaultPaymentInstrument": {
    "method": "payment-card",
    "paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N"
  },
  "preferredPayoutInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "customFields": {
    "foo": "bar"
  },
  "primaryAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": "Rebilly",
    "address": "36 Craven St",
    "address2": "string",
    "city": "Austin",
    "region": "Texas",
    "country": "GB",
    "postalCode": "WC2N 5NF",
    "phoneNumbers": [ … ],
    "emails": [ … ],
    "dob": "1980-04-01",
    "jobTitle": "CEO",
    "hash": "056ae6d97c788b9e98b049ebafd7b229bf852221"
  },
  "company": {
    "name": "string",
    "domain": "string",
    "yearFounded": 0,
    "industry": "string",
    "employeesCount": 0,
    "country": "string",
    "locality": "string",
    "_links": [ … ]
  },
  "averageValue": {
    "currency": "USD",
    "amount": 0.1,
    "amountUsd": 0.1
  },
  "paymentCount": 0,
  "lastPaymentTime": "2019-08-24T14:15:22Z",
  "lifetimeRevenue": {
    "currency": "USD",
    "amount": 0.1,
    "amountUsd": 0.1
  },
  "invoiceCount": 0,
  "tags": [
    { … }
  ],
  "revision": 0,
  "hasFulfilledKyc": true,
  "organizationId": "org_0YVDM8RC7GDADADSBSMW124JA8",
  "locale": "fr-FR",
  "taxNumbers": [
    { … }
  ],
  "personId": "prs_0YV7DDSDD1C8DA64KHH2W33CPF",
  "notificationEmails": [
    "user@example.com"
  ],
  "_links": [
    { … }
  ],
  "_embedded": {
    "defaultPaymentInstrument": {},
    "website": {},
    "leadSource": {}
  }
}