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)
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)
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.

_linksArray of objectsread-only
Related links.
_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": {}
  }
}