Customers

The Customer object represent your customer and the API allows you to create, update and retrieve your customers. You can retrieve a list of all your customers as well retrieve an individual customer.

Customer object

Attributes

id string

The object unique identifier.

address string

An address for this customer object.

aggregations object

An object with balance, sales, sales_current_period fields. Each field represent a summary for financial state of this customer.

contacts list

A list with many Contact objects related to this customer.

country string

Two-letter ISO code for the country of this customer. In list and retrieve API return calls a Country object.

currency string

Three-letter ISO code for the currency of this customer.

email string

A billing email address for this customer.

metadata object

A set of free key-value pairs that you will can attach to this customer. This can be useful for storing additional information about the object in a structured format.

name string

A name for this customer object.

phone string

A phone number for this customer object.

sources list

A list with many Source objects related to this customer.

state string

Six-letter max Piriod code for the state of this customer. In list and retrieve API return calls a State object.

tax_id string

A valid tax id for this customer.

tax_settings string

A set of key-value pairs that represent the legal tax agency specifications for this customer.

website string

A valid website url for this customer.

created datetime

Date and time of the creation of this customer.

updated datetime

Date and time of the last update of this customer.

{
    "id": "cus_dl6PTxQnTYy5BHYskV",
    "address": "ACME ST 909A",
    "aggregations": {
        "sales": 3757.00,
        "sales_current_period": 457.00,
        "balance": 457.00
    },
    "contacts": [],
    "country": {
        "id": "US",
        "name": "Estados Unidos",
        "name_en": "United states",
        "phone_code": "+1",
        "has_regulation": false,
        "tax_percent": 10
    },
    "currency": "USD",
    "email": "hello@acmetest.com",
    "metadata": {},
    "name": "ACME TEST LLC",
    "phone": "",
    "sources": [],
    "state": {
        "id": "USAZ",
        "code": "AZ",
        "name": "Arizona"
    },
    "tax_id": "897-56-9831",
    "tax_settings": {},
    "website": "",
    "created": "2020-10-15T13:26:15.356289-03:00",
    "updated": "2020-10-15T13:26:15.356321-03:00"
}

Create a customer

POST https://api.piriod.com/customers/

Creates a new Customer object.

Request Body

Name	Type	Description
address	string	An address for this customer object.
country	string	Two-letter ISO code for the country of this customer.
email	string	A billing email address for this customer.

Name

Type

Description

address

string

An address for this customer object.

country

string

Two-letter ISO code for the country of this customer.

string

A billing email address for this customer.

Retrieve a customer

GET https://api.piriod.com/customers/{{id}}/

Retrieves a Customer object.

Path Parameters

Name	Type	Description
id	string	ID of the Customer object.

Name

Type

Description

string

ID of the Customer object.

{
    "id": "cus_dl6PTxQnTYy5BHYskV",
    "address": "ACME ST 909A",
    "aggregations": {
        "sales": 3757.00,
        "sales_current_period": 457.00,
        "balance": 457.00
    },
    "contacts": [],
    "country": {
        "id": "US",
        "name": "Estados Unidos",
        "name_en": "United states",
        "phone_code": "+1",
        "has_regulation": false,
        "tax_percent": 10
    },
    "currency": "USD",
    "email": "hello@acmetest.com",
    "metadata": {},
    "name": "ACME TEST LLC",
    "phone": "",
    "sources": [],
    "state": {
        "id": "USAZ",
        "code": "AZ",
        "name": "Arizona"
    },
    "tax_id": "897-56-9831",
    "tax_settings": {},
    "website": "",
    "created": "2020-10-15T13:26:15.356289-03:00",
    "updated": "2020-10-15T13:26:15.356321-03:00"
}

Update a customer

PATCH https://api.piriod.com/customers/{{id}}/

Update a Customer object.

Path Parameters

Name	Type	Description
id	string	ID of the Customer object.

Name

Type

Description

string

ID of the Customer object.

Request Body

Name	Type	Description
email	string	A billing email address for this customer.
name	string	A name for this customer object.
website	string	A valid website url for this customer.

Name

Type

Description

string

A billing email address for this customer.

name

string

A name for this customer object.

website

string

A valid website url for this customer.

{
    "id": "cus_dl6PTxQnTYy5BHYskV",
    "address": "ACME ST 909A",
    "aggregations": {
        "sales": 3757.00,
        "sales_current_period": 457.00,
        "balance": 457.00
    },
    "contacts": [],
    "country": {
        "id": "US",
        "name": "Estados Unidos",
        "name_en": "United states",
        "phone_code": "+1",
        "has_regulation": false,
        "tax_percent": 10
    },
    "currency": "USD",
    "email": "hello@acmefinal.com",
    "metadata": {},
    "name": "ACME FINAL LLC",
    "phone": "",
    "sources": [],
    "state": {
        "id": "USAZ",
        "code": "AZ",
        "name": "Arizona"
    },
    "tax_id": "897-56-9831",
    "tax_settings": {},
    "website": "",
    "created": "2020-10-15T13:26:15.356289-03:00",
    "updated": "2020-10-15T13:26:15.356321-03:00"
}

List customers

GET https://api.piriod.com/customers/

Retrieves a list of Customer objects.

Query Parameters

Name	Type	Description
country__name	string	A country name to filter list results.

Name

Type

Description

country__name

string

A country name to filter list results.

{
    "count": 64,
    "next": "https://api.piriod.com/customers/?page=2&country=Estados",
    "previous": null,
    "results": [
        {
            "id": "cus_dl6PTxQnTYy5BHYskV",
            "address": "ACME ST 909A",
            "aggregations": {
                "sales": 3757.00,
                "sales_current_period": 457.00,
                "balance": 457.00
            },
            "contacts": [],
            "country": {
                "id": "US",
                "name": "Estados Unidos",
                "name_en": "United states",
                "phone_code": "+1",
                "has_regulation": false,
                "tax_percent": 10
            },
            "currency": "USD",
            "email": "hello@acmefinal.com",
            "metadata": {},
            "name": "ACME FINAL LLC",
            "phone": "",
            "sources": [],
            "state": {
                "id": "USAZ",
                "code": "AZ",
                "name": "Arizona"
            },
            "tax_id": "897-56-9831",
            "tax_settings": {},
            "website": "",
            "created": "2020-10-15T13:26:15.356289-03:00",
            "updated": "2020-10-15T13:26:15.356321-03:00"
        }
        ...
    ]
}

Available filter fields:

country
email
name
sources
tax_id
created

PreviousPagination and Filtering NextContacts

Last updated 2 years ago