Backend API: Manage company business unit addresses

This document describes how to manage company business unit addresses using the Backend API. An address belongs to a company and can be assigned to any number of that company’s business units.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the modules that provide the address endpoints and their installation instructions, see Install the Company Business Unit Addresses Backend API.

Conventions

Request headers, pagination, and the filter and sort syntax are the same for every Backend API resource—see Backend API conventions. This page lists only what is specific to business unit addresses.

How addresses relate to business units

An address is owned by a company, set through companyUuid when the address is created. Assigning it to a business unit is a separate step, done from the business unit side with addressUuids—see Edit a business unit.

This means:

• A newly created address belongs to a company but is assigned to no business unit.
• One address can be assigned to several business units of the same company. Such an address is listed once in the collection.
• Deleting a business unit does not delete its addresses; they stay with the company and lose the assignment.

Retrieve business unit addresses

To retrieve a paginated collection of addresses, send the request:

GET /company-business-unit-addresses

Request

Without either filter, the collection contains every address. A filter addressing any other property returns 400 with the error code 1215.

Without a sort parameter, the most recently created address appears first.

Response

{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/company-business-unit-addresses",
        "first": "https://glue-backend.mysprykershop.com/company-business-unit-addresses?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/company-business-unit-addresses?page[limit]=10&page[offset]=0"
    },
    "meta": {
        "pagination": {
            "numFound": 3,
            "currentPage": 1,
            "maxPage": 1,
            "currentItemsPerPage": 10
        }
    },
    "data": [
        {
            "type": "company-business-unit-addresses",
            "id": "9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58",
            "attributes": {
                "uuid": "9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58",
                "companyUuid": "0818f408-cc84-575d-ad54-92118a0e4273",
                "iso2Code": "DE",
                "street": "Julie-Wolfthorn-Straße",
                "number": "1",
                "additionToAddress": "Floor 3",
                "city": "Berlin",
                "zipCode": "10115",
                "comment": "Deliveries accepted between 9am and 5pm.",
                "labels": [
                    "contact person"
                ]
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/company-business-unit-addresses/9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58"
            }
        }
    ]
}

Retrieve a business unit address

To retrieve a single address, send the request:

GET /company-business-unit-addresses/{{address_uuid}}

Response

The response contains one address with the same attributes as Retrieve business unit addresses.

Create a business unit address

To create an address, send the request:

POST /company-business-unit-addresses

Request

Request sample: POST https://glue-backend.mysprykershop.com/company-business-unit-addresses

{
    "data": {
        "type": "company-business-unit-addresses",
        "attributes": {
            "companyUuid": "0818f408-cc84-575d-ad54-92118a0e4273",
            "iso2Code": "DE",
            "street": "Julie-Wolfthorn-Straße",
            "city": "Berlin",
            "zipCode": "10115"
        }
    }
}

Response

A successful request returns the 201 Created status code. The response contains the created address, with the same attributes as Retrieve a business unit address, and the uuid you use to address it afterwards—including when assigning it to a business unit.

Edit a business unit address

To update an address, send the request:

PATCH /company-business-unit-addresses/{{address_uuid}}

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/company-business-unit-addresses/9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58

{
    "data": {
        "type": "company-business-unit-addresses",
        "attributes": {
            "city": "Hamburg",
            "zipCode": "20095"
        }
    }
}

The request accepts the same writable attributes as Create a business unit address. All attributes are optional. The endpoint applies only the attributes present in the payload; every attribute you omit keeps its stored value.

Unlike a business unit, an address can be moved to another company: send companyUuid with the new owner.

Response

The response contains the updated address, with the same attributes as Retrieve a business unit address.

Possible errors

To view generic errors, see API errors and troubleshooting.