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

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.

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": "[e-mail]",
    "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.

200

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.

200 Returns a Customer object if a valid customer ID was provided.

{
    "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": "[e-mail]",
    "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.

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.

200 Customer object successfully updated.

{
    "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": "[e-mail]",
    "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.

200 A lists of Customer objects.

{
    "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": "[e-mail]",
            "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