Manage Buyers

The Buyers API is is designed to streamline and enhance the management of buyer information for partners. You can create buyers and make updates when the buyer information changes. You can also delete buyer records.

Create Buyers

To create a buyer, use the CreateBuyer endpoint. Each buyer is uniquely identified and tagged with the partner that created them.

Creating a buyer requires the following parameters:

  • phone_number: The buyer's phone number
  • email The buyer's email address
  • date_of_birth: The buyers date of birth
  • name :The buyer's first and last name
  • billing_address or home_address: The buyer's billing or home address.
  • disclosures: Provides disclosures to the buyer for permission to obtain and store their collected details.

You can collect this information from your front-end presented to the buyer as input fields. See the CreateCustomer example request below:

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/buyers \
     --header 'Country-Code: USA' \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'Locale: en_US' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": {
    "first_name": "Jane",
    "last_name": "Jordan"
  },
  "billing_address": {
    "street1": "650 California Street",
    "city": "San Francisco",
    "region1_code": "CA",
    "postal_code": "94108",
    "country_code": "US"
  },
  "disclosures": {
    "evidence": "disclosure evidence"
  },
  "phone_number": "+1-123-456-7890",
  "email": "[email protected]",
  "date_of_birth": "1990-01-31",
  "iovation_blackbox": "encrypted_string_token_here",
  "annual_income": 100000
}
'

Affirm returns a 201 response with the new buyer id:

{
  "id": "BUYER-ARI-1234",
  "status": "new",
  "is_synchronized": true,
  "is_income_stored": true
}

After creating a buyer, you can retrieve the details by buyerId using the RetrieveBuyer endpoint


Update Buyer

To update buyer details, call the UpdateBuyer endpoint and include the buyer_id. You can call the RetrieveBuyer endpoint to obtain the buyer_id. You can update the following buyer attributes:

  • phone_number
  • email
  • annual_income

The example below updates the following details:

  • Set's the new phone_number to +1-414-555-5555
  • Updates the email address to [email protected]
  • Updates the annual income to 125000
curl --request PUT \
     --url https://www.affirm.com/api/partner/v1/buyers/BUYER-ARI-1234 \
     --header 'Country-Code: USA' \
     --header 'Locale: en_US' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "phone_number": "+1-415-555-5555",
  "email": "[email protected]",
  "annual_income": 125000
}
'

Upon success, Affirm returns a 200 response with the updated customer details.


Delete Buyer

The DeleteBuyer request permanently removes a buyer from your system. You'll need the buyer_id when calling the API.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/buyers/BUYER-ARI-1234/delete_event \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json'

Upon success, Affirm returns a 201 response with the buyer_id of the buyer that was removed and a deleteId.

{
  "resource_id": "BUYER-ARI-1234",
  "delete_id": "123a4567-abcd-12ab-a345-123456789012"
}

Get Notification Eligibility

The RetrieveNotificationEligibility endpoint allows you retrieve information about the eligibility of a buyer to receive notifications. The endpoint requires the buyer_id and the message_type

curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/buyers/BUYER-ARI-1234/notification_eligibility?message_type=loan_payment_due' \
     --header 'accept: application/json'

Upon success, Affirm returns a 200 response indicating whether the buyer is set to receive push notifications:

{
  "push_notification": true
}