Customers

Create and manage customers. Customers represent the end users or businesses transacting on your platform and are the anchor for payment methods, subscriptions, and invoices.

The Customer object

Attributes
idstring

Unique identifier for the customer

objectstring

Object type identifier. Always customer.

emailstring

Customer email address

namenullable string

Customer full name

phonenullable string

Customer phone number

livemodeboolean

true if live mode, false if test mode

created_atstring
updated_atstring
THE CUSTOMER OBJECT
{
  "id": "235978d1-9081-45ce-a57d-e0a9659e8880",
  "object": "customer",
  "email": "marcia@example.com",
  "name": "Marcia Longo",
  "phone": "+13107484186",
  "livemode": false,
  "created_at": "2024-07-15T10:30:05Z",
  "updated_at": "2024-07-15T10:30:05Z"
}

List customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

A dictionary with a data property that contains an array of up to limit customers. Each entry in the array is a separate Customer object. If no more customers are available, the resulting array will be empty.

Query parameters
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

emailstringoptional

Filter by customer email

Returns

A paginated list of Customer objects

GET/v1/customers
curl --request GET \
  --url https://api.framepayments.com/v1/customers \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/customers",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "bb4c6def-a046-4b0a-a90d-0fa4c5518869",
      "name": "Gov. Daina Bergnaum",
      "email": "customer@frame.com",
      "description": "quia",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "payment_methods": [],
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1781115872,
      "updated": 1781115872,
      "livemode": false,
      "metadata": {}
    },
    {
      "id": "c9a68978-ad2b-47d9-b5f5-4eb1e4352f39",
      "name": "Toby Considine",
      "email": "customer@frame.com",
      "description": "illo",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "payment_methods": [],
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1781115872,
      "updated": 1781115872,
      "livemode": false,
      "metadata": {}
    },
    {
      "id": "771271b8-1107-4777-899c-83e730e25c05",
      "name": "Riva Jakubowski",
      "email": "customer@frame.com",
      "description": "omnis",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "payment_methods": [],
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1781115872,
      "updated": 1781115872,
      "livemode": false,
      "metadata": {}
    }
  ]
}

Create customer

Creates a new Customer object. Returns the Customer object after successful Customer creation. Returns an error if create parameters are invalid.

Body parameters
emailstringrequired

The customer's email address.

namestringoptional

The customer's full name or business name.

phonestringoptional

The customer's phone number.

descriptionstringoptional

An arbitrary string attached to the object. Often useful for displaying to users.

ssnstringoptional

The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format. This field never returned in API responses.

date_of_birthstringoptional

The customer's date of birth in YYYY-MM-DD format.

metadataobjectoptional

Additional custom metadata for the customer

Returns

Returns the Customer object after successful Customer creation

POST/v1/customers
curl --request POST \
  --url https://api.framepayments.com/v1/customers \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "user@example.com"
}'
RESPONSE
{
  "id": "b6171c6f-4b2a-4248-9eab-265071cd60b8",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "description": null,
  "status": "active",
  "date_of_birth": null,
  "phone": "+1 (310) 748-4186",
  "payment_methods": [],
  "billing_address": null,
  "shipping_address": null,
  "object": "customer",
  "created": 1781115873,
  "updated": 1781115873,
  "livemode": false,
  "metadata": {}
}

Get customer

Retrieves a Customer object. Returns the Customer object for a valid identifier. If it's for a deleted Customer, a subset of the customer's information is returned, including a deleted property that's set to true.

Path parameters
idstringrequired

Customer ID

Returns

Returns the Customer object for a valid identifier

GET/v1/customers/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "5cc3bef2-8551-4ed5-8d60-85636c407df3",
  "name": "Sen. Lincoln Strosin",
  "email": "customer@frame.com",
  "description": "perspiciatis",
  "status": "active",
  "date_of_birth": null,
  "phone": "+13107484186",
  "payment_methods": [],
  "billing_address": null,
  "shipping_address": null,
  "object": "customer",
  "created": 1781115873,
  "updated": 1781115873,
  "livemode": false,
  "metadata": {}
}

Update customer

Updates the specified Customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the Customer creation call.

Returns the Customer object if the update succeeded. Returns an error if update parameters are invalid.

Path parameters
idstringrequired

Customer ID

Body parameters
namestringoptional

The customer's full name or business name.

emailstringoptional

The customer's email address.

phonestringoptional

The customer's phone number.

descriptionstringoptional

An arbitrary string attached to the object. Often useful for displaying to users.

ssnstringoptional

The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format. This field is never returned in API responses. Cannot be removed once set.

date_of_birthstringoptional

The customer's date of birth in YYYY-MM-DD format. Cannot be removed once set.

metadataobjectoptional
Returns

Returns the Customer object if the update succeeded

PATCH/v1/customers/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d9a45863-643a-439f-bb01-a026c299a36f",
  "name": "New Name",
  "email": "customer@frame.com",
  "description": "similique",
  "status": "active",
  "date_of_birth": null,
  "phone": "+13107484186",
  "payment_methods": [],
  "billing_address": null,
  "shipping_address": null,
  "object": "customer",
  "created": 1781115873,
  "updated": 1781115873,
  "livemode": false,
  "metadata": {}
}

Delete customer

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

Returns an object with a deleted parameter on success. If the Customer ID does not exist, this call returns an error. Unlike other objects, deleted customers can still be retrieved through the API in order to be able to track their history. Deleting customers removes all credit card details and prevents any further operations to be performed (such as adding a new subscription).

Path parameters
idstringrequired

Customer ID

Returns

Returns an object with a deleted parameter on success

DELETE/v1/customers/{id}
curl --request DELETE \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "aba72447-9b2d-465a-9563-84e9f79aba5c",
  "object": "customer",
  "deleted": true
}

List customer payment methods

Retrieve a paginated list of payment methods for a customer

Path parameters
idstringrequired

Customer ID

Query parameters
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A paginated list of PaymentMethod objects for the customer

GET/v1/customers/{id}/payment_methods
curl --request GET \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/payment_methods \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/customers/c74bb87d-dc28-4c55-9ac2-a08a8562ae25/payment_methods",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": []
}

Block customer

Blocks an active customer, preventing all future payment activities. All payment methods associated with the Customer become blocked.

Returns the Customer object if the block succeeded. Returns an error if block parameters are invalid.

Path parameters
idstringrequired

Customer ID

Returns

Returns the Customer object after successfully blocking the customer

POST/v1/customers/{id}/block
curl --request POST \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/block \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "d03268d0-f9da-4eef-8b64-8a78ccc022df",
  "name": "Dewayne Wehner JD",
  "email": "customer@frame.com",
  "description": "est",
  "status": "blocked",
  "date_of_birth": null,
  "phone": "+13107484186",
  "payment_methods": [],
  "billing_address": null,
  "shipping_address": null,
  "object": "customer",
  "created": 1781115874,
  "updated": 1781115874,
  "livemode": false,
  "metadata": {}
}

Unblock customer

Reactivates a blocked customer, allowing them to resume payment activities.

Returns the Customer object if the unblock succeeded. Returns an error if unblock parameters are invalid.

Path parameters
idstringrequired

Customer ID

Returns

Returns the Customer object after successfully unblocking the customer

POST/v1/customers/{id}/unblock
curl --request POST \
  --url https://api.framepayments.com/v1/customers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/unblock \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "e1218789-63af-461e-bf49-89ce2b3b4510",
  "name": "Sam Hilpert Esq.",
  "email": "customer@frame.com",
  "description": "omnis",
  "status": "active",
  "date_of_birth": null,
  "phone": "+13107484186",
  "payment_methods": [],
  "billing_address": null,
  "shipping_address": null,
  "object": "customer",
  "created": 1781115874,
  "updated": 1781115874,
  "livemode": false,
  "metadata": {}
}

Search customers

Search for customers you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages.

Returns a dictionary with a data property that contains an array of up to limit customers. If no objects match the query, the resulting array will be empty.

Query parameters
qstringoptional

Search query (email, name, phone)

namestringoptional

The customer's full name or business name.

emailstringoptional

The customer's email address.

phonestringoptional

The customer's phone number.

created_beforeintegeroptional

Time at which the object was created. Measured in seconds since the Unix epoch.

created_afterintegeroptional

Time at which the object was created. Measured in seconds since the Unix epoch.

pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A dictionary with a data property containing an array of matching Customer objects

GET/v1/customers/search
curl --request GET \
  --url https://api.framepayments.com/v1/customers/search \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/customers/search?name=John+Doe",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "348df4f6-25b1-4089-a061-a2c7c287c635",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "description": "deserunt",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "payment_methods": [],
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1781115874,
      "updated": 1781115874,
      "livemode": false,
      "metadata": {}
    }
  ]
}