Api Reference

Customers

On this page, we'll dive into the different customer endpoints you can use to manage your Vatly customers programmatically.

The Customer API Resource

Below you'll find all properties for the Vatly Customer API resource.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the customer (starts with `customer_`).
`resource`	`string`	The resource type. Always `customer`.
`testmode`	`boolean`	Whether this resource is in test mode.
`email`	`string`	The email address for the customer.
`name`	`string \| null`	The customer's display / account-holder name. An identity field used for communication (dunning emails, dashboard) — distinct from, and with no effect on, the billing name on invoices.
`createdAt`	`string`	When this customer was created (ISO 8601 format).
`metadata`	`object \| null`	Arbitrary key-value metadata for your application. Up to 50 keys, with key names up to 40 characters and values up to 500 characters.
`links`	`object`	HATEOAS links to related resources. Contains `self` link.

List all customers

GET /v1/customers

This endpoint allows you to retrieve a paginated list of all your customers. By default, a maximum of ten customers are shown per page.

Optional attributes

Name	Type	Description
`limit`	`integer`	The number of customers to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this customer ID.
`endingBefore`	`string`	A cursor for use in pagination. Returns results before this customer ID.

curl -G https://api.vatly.com/v1/customers \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$customers = $vatly->customers->page();

{
  "data": [
    {
      "id": "customer_7kBmRtPvXw2NjLhYcZaE",
      "resource": "customer",
      "testmode": false,
      "email": "john.doe@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "userId": "user_Qp8kNvBxKw7RjTgYcZaE"
      },
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE",
          "type": "application/json"
        }
      }
    },
    {
      "id": "customer_Lp3mNvBxKw7RjTgYcZaE",
      "resource": "customer",
      "testmode": false,
      "email": "jane.smith@acme.com",
      "name": "Jane Smith",
      "createdAt": "2024-01-10T08:15:00Z",
      "metadata": {},
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE",
          "type": "application/json"
        }
      }
    }
  ],
  "count": 2,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/customers",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  }
}

Create a customer

POST /v1/customers

This endpoint allows you to add a new customer to Vatly. To add a customer, you must provide their email address.

Customers are uniquely identified by email within each testmode. Creating a customer with an email that already exists will return a validation error.

Required attributes

Name	Type	Description
`email`	`string`	The email address for the customer. Must be unique within the merchant's account for the given testmode.

Optional attributes

Name	Type	Description
`name`	`string`	The customer's display / account-holder name (max 255 characters).
`metadata`	`object`	Arbitrary key-value metadata for your application.

curl https://api.vatly.com/v1/customers \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@example.com", "metadata": {"userId": "user_Qp8kNvBxKw7RjTgYcZaE"}}'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$vatly->customers->create([
  'email' => 'customer@example.com',
  'metadata' => [
    'userId' => 'user_Qp8kNvBxKw7RjTgYcZaE',
  ],
]);

{
  "id": "customer_7kBmRtPvXw2NjLhYcZaE",
  "resource": "customer",
  "testmode": false,
  "email": "customer@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "userId": "user_Qp8kNvBxKw7RjTgYcZaE"
  },
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE",
      "type": "application/json"
    }
  }
}

Retrieve a customer

GET /v1/customers/:id

This endpoint allows you to retrieve a customer by providing their Vatly id. Refer to the list at the top of this page to see which properties are included with customer objects.

curl https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$vatly->customers->get('customer_7kBmRtPvXw2NjLhYcZaE');

{
  "id": "customer_7kBmRtPvXw2NjLhYcZaE",
  "resource": "customer",
  "testmode": false,
  "email": "john.doe@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "userId": "user_Qp8kNvBxKw7RjTgYcZaE"
  },
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE",
      "type": "application/json"
    }
  }
}

Update a customer

PATCH /v1/customers/:id

Updates a customer's identity fields. Only name and email may be changed here, and both are optional — send whichever you want to update.

Billing-address details (company name, tax ID, street, city, country, etc.) are not supported by this endpoint and are ignored. Amend those through the hosted billing-update flow, which validates tax-relevant data centrally so invoices stay accurate.

Optional attributes

Name	Type	Description
`name`	`string \| null`	The customer's display / account-holder name (max 255 characters).
`email`	`string`	The customer's email address. Must be unique within the merchant's account for the given testmode.

curl -X PATCH https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "new.email@example.com"}'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$customer = $vatly->customers->update('customer_7kBmRtPvXw2NjLhYcZaE', [
  'name' => 'John Doe',
  'email' => 'new.email@example.com',
]);

{
  "id": "customer_7kBmRtPvXw2NjLhYcZaE",
  "resource": "customer",
  "testmode": false,
  "email": "new.email@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "userId": "user_Qp8kNvBxKw7RjTgYcZaE"
  },
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE",
      "type": "application/json"
    }
  }
}

Edit this pageorReport an issue

Testing

Use test helper endpoints to simulate billing events like subscription renewals in sandbox mode.

Webhook Endpoints

Register and manage the endpoints Vatly delivers webhook events to — create, list, update, and delete them programmatically.