Developers/Client/JSONAPI/Managing basket addresses

From Aimeos documentation

< Developers‎ | Client/JSONAPI

<languages/>


<translate> By default, you can add a billing and delivery address to the basket. While the delivery address is optional, setting the billing address is almost always mandatory.

Set addresses

To add one or more addresses, you have to pass the data including the "id" and the attributes in a POST request to the server. The "id" must be the type of the address, i.e. "payment" for the billing address and "delivery" for the corresponding address.

There are some address attributes that are required when adding or replacing an address:

  • order.base.address.lastname (last name or full name)
  • order.base.address.address1 (most of the time the street name)
  • order.base.address.city (town or city name)
  • order.base.address.languageid (language the customer prefers)
  • order.base.address.email (account e-mail address)

The Javascript code for creating the POST request could look like:

var params = {data: [{
    id: "payment", // or "delivery"
    attributes: {
        "order.base.address.addressid": "..." // customer address ID (optional)
        "order.base.address.salutation": "mr" // or "mrs", "miss", "company" (optional)
        "order.base.address.company": "..." // (optional)
        "order.base.address.vatid": "..." // (optional)
        "order.base.address.title": "..." // (optional)
        "order.base.address.firstname": "..." // (optional)
        "order.base.address.lastname": "..." // (required)
        "order.base.address.address1": "..." // (required)
        "order.base.address.address2": "..." // (optional)
        "order.base.address.address3": "..." // (optional)
        "order.base.address.postal": "..." // (optional)
        "order.base.address.city": "..." // (required)
        "order.base.address.state": "..." // (optional)
        "order.base.address.countryid": "..." // (optional)
        "order.base.address.languageid": "..." // (required by many payment gateways)
        "order.base.address.telefax": "..." // (optional)
        "order.base.address.email": "..." // (required)
        "order.base.address.website": "..." // (optional)
        "order.base.address.longitude": "..." // (optional, float value)
        "order.base.address.latitude": "..." // (optional, float value)
    }
}]};
 
var url = response['links']['basket/address']['href']; // from basket response
 
if(response['meta']['csrf']) { // add CSRF token if available and therefore required
    var csrf = {};
    csrf[response['meta']['csrf']['name']] = response['meta']['csrf']['value']; 
    url += (url.indexOf('?') === -1 ? '?' : '&') + $.param(csrf);
}
 
$.ajax({
    url: url,
    method: "POST",
    dataType: "json",
    data: JSON.stringify(params)
}).done( function( result ) {
    console.log( result );
});

The response will then contain an additional "relationships" section in the basket data that points to the new address in the "included" section:

{
    "meta": {
        "total": 1,
        "prefix": null,
        "content-baseurl": "/"
    },
    "links": {
        "self": {
            "href": "http://localhost/jsonapi/basket/default/address",
            "allow": ["DELETE","GET"]
        },
        // ...
    },
    "data": {
        "id": "default",
        "type": "basket",
        "links": {
            "self": {
                "href": "http://localhost/jsonapi/basket/default",
                "allow": ["DELETE", "GET", "PATCH", "POST"]
            }
        },
        "attributes": {
            "order.base.id": null,
            "order.base.customerid": "",
            "order.base.sitecode": "",
            "order.base.languageid": "en",
            "order.base.currencyid": "EUR",
            "order.base.price": "0.00",
            "order.base.costs": "0.00",
            "order.base.rebate": "0.00",
            "order.base.status": 0,
            "order.base.comment": ""
        },
        "relationships": {
            "basket/service": {
                "data": [{
                    "type": "basket/address",
                    "id": "payment"
                }]
            }
        }
    },
    "included": [{
        "id": "payment",
        "type": "basket/address",
        "attributes": {
            "order.base.address.id": null,
            "order.base.address.addressid": "",
            "order.base.address.salutation": "",
            "order.base.address.company": "",
            "order.base.address.vatid": "",
            "order.base.address.title": "",
            "order.base.address.firstname": "",
            "order.base.address.lastname": "test",
            "order.base.address.address1": "",
            "order.base.address.address2": "",
            "order.base.address.address3": "",
            "order.base.address.postal": "",
            "order.base.address.city": "",
            "order.base.address.state": "",
            "order.base.address.countryid": null,
            "order.base.address.languageid": null,
            "order.base.address.telephone": "",
            "order.base.address.telefax": "",
            "order.base.address.email": "",
            "order.base.address.website": "",
            "order.base.address.longitude": null,
            "order.base.address.latitude": null,
            "order.base.address.flag": 0,
            "order.base.address.type": "payment"
        },
        "links": {
            "self": {
                "href": "http://localhost/jsonapi/basket/default/address/payment",
                "allow": ["DELETE"]
            }
        }
    }]
}

Depending on the activated basket plugins, the content of the response can be modified more than that. Especially, as the address is often the basis for the available delivery options.

Delete addresses

You can also remove addresses from the basket again by using a DELETE request to the URL of the address in the basket. In our example above, the URL is:

http://localhost/jsonapi/basket/default/address/payment

The DELETE request can be constructed in that way:

// basket address URL returned from basket response
var url = response['included'][0]['links']['self']['href'];
 
if(response['meta']['csrf']) { // add CSRF token if available and therefore required
    var csrf = {};
    csrf[response['meta']['csrf']['name']] = response['meta']['csrf']['value']; 
    url += (url.indexOf('?') === -1 ? '?' : '&') + $.param(csrf);
}
 
$.ajax({
    url: url,
    method: "DELETE",
    dataType: "json"
}).done( function( result ) {
    console.log( result );
});

This request will remove the address entry from the basket and the response won't contain the address in the "included" section as well the corresponding "relationships" entry any more.

</translate>