• Version: 1.2.0

Addresses

Addresses allow you to store multiple mailing or billing addresses for a single customers. You can name these addresses and store them directly on the customer itself. The address endpoint extends off of the customers/{ID number} endpoint - https://api.molt.in/v1/customers/{CUSTOMER ID}/addresses. Address data is not stored using the customers endpoint itself because you can record any number of addresses per customer.

Addresses are flows-based structures with the following data fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the address.
order Array No No Links to any orders placed with this address.
created_at String No No Automatically populated when you create the address.
updated_at String No No Automatically populated when you modify the address.
save_as String No Yes The name under which this address is saved. You can display this name to the customer when you ask them to select from their saved addresses.
first_name String Yes No The first name of the recipient on this address.
last_name String Yes No The last name of the recipient on this address.
address_1 String Yes No The first portion of the address, usually the street address.
address_2 String No No The second portion of the address, usually an apartment or unit number.
postcode String Yes No The ZIP Code, Postcode, or other postal reference string for this delivery address.
country String/Multiple Yes No When entering addresses, use the two-digit country code. This field will return an array with additional information based on that country code.
company String No No The company or other organization at this address.
city String No No The city in which this address is located.
customer Array No No A link to the customer information associated with this address.
phone String No No The phone number used to reach the recipient at this address.
county String No No The county or state for this address.
instructions String No No Any special delivery instructions for the shipping company.

Before using addresses, you’ll need to create them with the https://api.molt.in/v1/customers/{CUSTOMER ID}/addresses endpoint. Once created, addresses can be set as billing or shipping addresses on orders.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Address

By default, new customers do not have any addresses, so you will need to create any that you want to use. Every address that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/customers/:id/addresses \
  -H "Authorization: Bearer XXXX" \
  -d "save_as=Home" \
  -d "first_name=John" \
  -d "last_name=Doe" \
  -d "address_1=123 Main St." \
  -d "city=Springfield" \
  -d "county=MA" \
  -d "postcode=123456" \
  -d "country=US"

This call will return the address information for the newly created address, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "id":"1060315797949251666",
    "order":null,
    "created_at":"2015-08-26 20:05:12",
    "updated_at":"2015-08-26 20:11:29",
    "save_as":"Home",
    "first_name":"John",
    "last_name":"Doe",
    "address_1":"123 Main St.",
    "address_2":"",
    "postcode":"123456",
    "country":
    {
      "value":"United States",
      "data":
      {
        "code":"US",
        "name":"United States"
      }
    },
    "company":"",
    "city":"Springfield",
    "customer":
    {
      "value":"John",
      "data":
      {
        "id":"1055961503028478872",
        "order":null,
        "created_at":"2015-08-20 19:53:59",
        "updated_at":"2015-08-20 19:53:59",
        "first_name":"John",
        "last_name":"Doe",
        "email":"support@moltin.com",
        "group":null
      }
    },
    "phone":"",
    "county":"MA",
    "instructions":""
  }
}

The address actions below will return information in this same format.

Retrieve Address Information

Once you have created addresses for your customers, you have two methods to retrieve that information. The first requires that you know the ID number of the address that you want, and it returns solely the information for that one address. The second returns an array of all addresses associated with a customer.

Retrieve a Single Address by ID

You can GET information for a single address by adding the ID number to the addresses endpoint. No additional data fields are required.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/customers/:id/addresses/:addressId
  -H "Authorization: Bearer XXXX"

Retrieve a List of All Addresses

Using the https://api.molt.in/v1/customers/:id/addresses endpoint, you can return an array that contains all of the addresses that you have created.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/customers/:id/addresses \
-H "Authorization: Bearer XXXX"

This will return an array of address information, as shown in the Create an Address section.

Edit an Address

To change one or more values in a single address, use a PUT call with the customers/{ID number}/addresses endpoint. You can change most field values through this method, including updating street addresses, adding special instructions, or changing the saved name.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/customers/:id/addresses/:addressId
-H "Authorization: Bearer XXXX"
-d "instructions=Don't make eye contact with our neighbor. He's a talker."

Delete a Single Address

To remove an address, you use the same customers/{ID number}/addresses endpoint we used to retrieve a single address, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/customers/:id/addresses/:addressId
  -H "Authorization: Bearer XXXX"

If successful, this call will return the following:

{
	"status":true,
	"message":"Address removed successfully"
}

Please note that if you delete a customer, all associated addresses will be deleted as well.

Get a list of address fields

You can get a list of address fields like so:

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/categories/fields
	-H "Authorization: Bearer XXXX"

You can also use this to build a simple form:

This functionality may be limited by access token scope. See Types of Tokens for more information.

$fields = Address::Fields('<CUSTOMER ID>', null, true);

echo '<form method="address/create" action="post">';
foreach ( $fields as $field ) {
    echo '<label for="'.$field['slug'].'">'.$field['title'].'</label>';
    echo $field['input'];
}
echo '<button type="submit">Create</button>';
echo '</form>';