v2.5.0 Release: Address creation

You can register a customer’s location through the API. The address is the site later work hangs off, devices, readings, and pool membership all refer to it by the identifier you receive at creation.

Send the location. Everything else is optional.

A successful create returns the address as stored, including its identifier.

The address is filed under your own account. You do not name a tenant in the request, and you cannot move an address to another tenant afterwards.

What to keep

Store the uuid from the response. That is the only way to refer to the address later. There is no search by street, postal code, or customer.

You can read it back and correct details after creation:

• GET /api/v2/addresses/{address_uuid} — read one address
• PATCH /api/v2/addresses/{address_uuid} — change only the fields you send. Sending a new city leaves the street and postal code as they were

An address that is not yours is reported as not found.

If a create fails

Do not send the same create again until you know whether the first one landed. The identifier is assigned when the request is accepted, so a timeout or a temporary outage can still have created the address.

When the error body includes details.addressUuid, read that address before retrying. A second create always makes a second address. There is no way to find the first one from the street or postal code if that identifier was never received.

Address behaviour

Creating the address is enough to have a site on record. A few limits around that record, and one separate step for the customer, are what usually surprises people.

Account setup

The account has to be switched on for this. The calls are refused until Chargee has enabled address management on the API account and assigned it to your tenant. You do not send a tenant in the request. The response shows which tenant the address was filed under, and that value never changes.

No list and no delete

You can only fetch an address by the identifier from the create response. A wrong create stays. Correct it with a patch, or stop using that identifier. Sending an empty house-number addition clears it. Any other field you leave out of a patch stays as it was.

Customer access

A customer is not created with the address. To let someone use the site, connect a customer who is already registered with Chargee, using the sub from that registration. The access level is required: admin or guest.

• POST /api/v2/addresses/{address_uuid}/access grants access. Repeating it for someone who already has access returns a conflict. Change the level with a patch instead.
• PATCH /api/v2/addresses/{address_uuid}/access/{sub} changes the level. It does not create a grant.
• DELETE /api/v2/addresses/{address_uuid}/access/{sub} ends access. The grant stays in the history, with the time it ended.
• GET /api/v2/addresses/{address_uuid}/access lists who has access.

Put the sub in the path only after URL-encoding it. Some customer identifiers contain /. A customer who is not registered yet, or who belongs to another tenant, is reported as not found — the same answer as an address you do not own.

Connecting a customer can fail even when the address create succeeded. The address calls do not depend on the customer being available yet. The access calls do. A customer you have just registered may still come back as not found until that registration is visible. Listing access can show a grant whose name, email, and sub are missing; that grant is real, but you cannot change or revoke it through the API until the sub is present.

The address identifier is also what you use later when you add that site to a curtailment pool.