Customers & Addresses Yep REST API — Endpoints, EAV attributes & defaults

Overview

The /api2/customers route is an integration/administrative endpoint, designed for profile synchronization with ERPs, CRMs and back-offices. The /api2/address route centralizes the address lifecycle — create, update, list and delete — preserving Yep semantics for default billing and shipping.

200

Max limitPer page on GET /api2/customers via limit.

20

Default limitApplied when limit is omitted.

EAV

Dynamic attributesSearch and update by any EAV attribute on customer.

2x

Default markersis_default_billing and is_default_shipping per address.

All endpoints require Authorization: Bearer {token}. Parameters can be sent via query string or JSON body on GET, whichever is more convenient for the integrator.

Customers

Full CRUD over the customer profile with deterministic listing, individual lookup by ID and search by attribute (email, taxvat, mobile or any EAV).

GET/api2/customers

List customers with deterministic pagination.

JSONCustomers

page Optional

Integer. Current page. Default: 1.

limit Optional

Integer. Page size. Default: 20; maximum: 200. Invalid values are normalized to the default.

include_pagination Optional

Boolean. When true, returns total, last_page and has_next in the response body.

Request

{
  "page": 1,
  "limit": 20,
  "include_pagination": true
}

Response

{
  "success": true,
  "page": 1,
  "limit": 20,
  "total": 150,
  "last_page": 8,
  "has_next": true,
  "customers": [
    {
      "customer_id": 123,
      "email": "customer@email.com",
      "firstname": "John",
      "lastname": "Smith",
      "taxvat": "123.456.789-00",
      "celular": "11999999999",
      "custom_attributes": {
        "celular": "11999999999"
      }
    }
  ]
}

GET/api2/customersby ID

Look up a specific customer by Yep ID.

{
  "id": 123
}

{
  "success": true,
  "customer": {
    "customer_id": 123,
    "email": "customer@email.com",
    "firstname": "John",
    "lastname": "Smith",
    "taxvat": "123.456.789-00",
    "custom_attributes": {}
  }
}

GET/api2/customersby attribute

Search by email, taxvat, the cpf alias or any EAV attribute available on customer — including custom ones such as celular.

{
  "attribute": "email",
  "value": "customer@email.com"
}

{
  "attribute": "celular",
  "value": "11999999999"
}

Shorthand payloads are also accepted, without the attribute/value wrapper:

{
  "email": "customer@email.com"
}

{
  "taxvat": "12.345.678/0001-99"
}

PATCH/api2/customers

Update customer data. The id field is required.

{
  "id": 123,
  "firstname": "John",
  "lastname": "Smith",
  "email": "john@email.com",
  "taxvat": "12.345.678/0001-99",
  "celular": "11999999999"
}

Custom attributes can also be grouped under custom_attributes.

{
  "id": 123,
  "custom_attributes": {
    "celular": "11999999999",
    "marketplace_comissao": "10"
  }
}

{
  "success": true,
  "customer": {
    "customer_id": 123,
    "email": "john@email.com",
    "taxvat": "12.345.678/0001-99",
    "celular": "11999999999",
    "custom_attributes": {
      "celular": "11999999999"
    }
  }
}

The canonical CPF/CNPJ field is taxvat, following the Yep standard. The cpf alias may be used as input, but the response always normalizes to taxvat.

DELETE/api2/customers

Remove the customer account. The id field is required.

{
  "id": 123
}

{
  "success": true,
  "message": "Customer removed successfully.",
  "customer_id": 123
}

Customer attributes

Consolidated reference of the supported fields when reading and updating customer profiles.

Standard fields

email, firstname, middlename, lastname
taxvat, dob, gender
group_id, website_id, store_id

CPF/CNPJ

The canonical field is taxvat, following the Yep standard. The cpf alias may be used as input, but the response always normalizes to taxvat.

Customizable attributes

Any EAV attribute available on customer, such as celular or marketplace_comissao, can be read and updated. They are accepted both at the payload root and grouped under custom_attributes.

Recommendation

Whenever possible, send custom attributes inside custom_attributes. This avoids ambiguity with standard fields and keeps the contract ready for future profile evolutions.

Addresses

Full address lifecycle for customers, accepting both address_id and the id alias, with default-marker support and backward compatibility for the legacy /api2/customers/addresses/{customer_id} route.

GET/api2/address?customer_id=123

List addresses of a customer.

{
  "success": true,
  "customer_id": 123,
  "default_billing_id": 10,
  "default_shipping_id": 11,
  "addresses": [
    {
      "address_id": 10,
      "customer_id": 123,
      "is_default_billing": true,
      "is_default_shipping": false,
      "firstname": "John",
      "lastname": "Smith",
      "street": ["Main Street", "123"],
      "city": "São Paulo",
      "region": "SP",
      "postcode": "01000-000",
      "country_id": "BR",
      "telephone": "11999999999",
      "custom_attributes": {}
    }
  ]
}

Backward compatibility is preserved through the legacy route:

GET /api2/customers/addresses/123

GET/api2/address?address_id=456

Look up a specific address. id is also accepted in place of address_id.

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": true,
    "is_default_shipping": false,
    "firstname": "John",
    "lastname": "Smith"
  }
}

POST/api2/address

Create a new address for the customer. The customer_id field is required.

{
  "customer_id": 123,
  "firstname": "John",
  "lastname": "Smith",
  "street": ["Main Street", "123", "Apt 2"],
  "city": "São Paulo",
  "region": "SP",
  "postcode": "01000-000",
  "country_id": "BR",
  "telephone": "11999999999",
  "is_default_billing": true,
  "is_default_shipping": true
}

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": true,
    "is_default_shipping": true
  },
  "invalid_fields": []
}

PATCH/api2/address

Update an existing address. Accepts address_id or id.

{
  "address_id": 456,
  "telephone": "11888888888",
  "is_default_shipping": true
}

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": false,
    "is_default_shipping": true,
    "telephone": "11888888888"
  }
}

DELETE/api2/address

Remove an existing address. Accepts address_id or id.

{
  "address_id": 456
}

{
  "success": true,
  "message": "Address removed successfully.",
  "address_id": 456,
  "customer_id": 123
}

Default markers New

Each address returns the is_default_billing and is_default_shipping booleans, reflecting the relationship with the customer profile. Both can be modified on POST and PATCH.

is_default_billing Optional

Boolean. When true, marks this address as the default billing in the customer profile.

is_default_shipping Optional

Boolean. When true, marks this address as the default shipping in the customer profile.

Behavior when removing the marker

Sending is_default_billing or is_default_shipping as false removes the marker from the profile only when the current address is the corresponding default. In other cases, the field is ignored.

Supported usage patterns

Quick reference for tested and certified combinations on customers and addresses.

Default listing GET /api2/customers

Paginated with metadata GET /api2/customers?page=1&limit=100&include_pagination=1

Lookup by ID GET /api2/customers + {"id":123}

Lookup by email GET /api2/customers + {"email":"customer@email.com"}

Lookup by taxvat (CPF/CNPJ) GET /api2/customers + {"taxvat":"12.345.678/0001-99"}

Lookup by EAV attribute GET /api2/customers + {"attribute":"celular","value":"11999999999"}

Customer addresses GET /api2/address?customer_id=123

Single address GET /api2/address?address_id=456

Legacy compatibility GET /api2/customers/addresses/123

Integration recommendations

Consolidated best practices for customer and address synchronization with ERPs and CRMs.

Use taxvat as the canonical CPF/CNPJ key — the cpf alias is for input only.
Prefer custom_attributes for any attribute outside the standard set, avoiding collisions with native Yep fields.
Combine limit=100 + include_pagination=1 to paginate with a reliable stop criterion (has_next=false).
Always pass is_default_billing and is_default_shipping explicitly when creating or updating critical addresses.

Avoid

Relying on the legacy /api2/customers/addresses/{id} route for new integrations — prefer /api2/address.
Updating default markers without first checking the customer's default_billing_id and default_shipping_id.
Treating cpf as the canonical field — the response always normalizes to taxvat.

Sync tip

For CRM integrations, start with a GET /api2/customers call using include_pagination=1 to discover the base size, then parallelize GET /api2/address?customer_id={id} only for active customers in the period — reducing load and respecting the 200 per-page limit.

Common errors

Status	Example	When it occurs
`400`	`{"error":"Invalid JSON."}`	Malformed JSON body or invalid parameter.
`401`	`{"error":"Missing or malformed token."}`	Missing, expired, invalid or revoked token.
`404`	`{"error":"Customer not found."}`	Customer or address does not exist.

Customers & addresses

Overview

Customers

Request

Response

Customer attributes

Standard fields

CPF/CNPJ

Customizable attributes

Recommendation

Addresses

Default markers New

Behavior when removing the marker

Supported usage patterns

Integration recommendations

Recommended

Avoid

Sync tip

Common errors