페이지 이동경로
  • Docs>
  • Kakao Sync>
  • Retrieve shipping address

Kakao Sync

Retrieve shipping address

This API enables you to retrieve shipping addresses saved in the Kakao Account. You need an access token or your app's Admin key and the user's consent to retrieve shipping addresses as the Requesting user information API needs.

Even though a user consents, if Kakao does not retain a user's shipping address, Kakao cannot provide the information to your linked services as well. If a shipping address is required for your service, set 'Shipping information' to 'Required consent' and use the Provision after collecting information option in [My Application] > [Kakao Login] > [Consent items].

You can test this feature in [Tools] > [REST API Test].

Tag used in this document

Tag Description
Login required The API marked with this tag requires Kakao Login. You must implement the Kakao Login function first, and then call the corresponding API by using the access token issued when a user logs in.

Web Login required

You can request a user's shipping address with either an access token or your app's Admin key. For a service administrator, make a request from a server by using the Admin key in the request header, and specify target_id for a service user ID to be retrieved.

If shipping_addresses is not returned in the response, see the value of shipping_addresses_needs_agreement to check if a user's consent is required.

If its value is true, you can get the user's consent to shipping addresses by requesting additional consent, and then retrieve shipping address. If false, you cannot get any shipping address regardless of a user's consent. In this case, you should collect shipping addresses from a user internally.

Request

Using Access Token

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
Name Type Description Required
address_id Long If there are multiple shipping addresses, specify an address ID to get a specific shipping address. X
from_updated_at Integer If multiple shipping addresses return through multiple pages, only the shipping addresses that are changed after the updated_at time return.
The last shipping address on the previous page is used for an input value for the next page.
If set to 0, shipping addresses are retrieved from the beginning.
X
page_size Integer Number of (two or more) shipping addresses displayed on a page.
(Default: 10)
X

Using Admin key

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id
O
target_id Long Service user ID. O
Response
Key
Name Type Description Required
user_id Long Service user ID. O
shipping_addresses ShippingAddress[] A list of shipping addresses. X
shipping_addresses_needs_agreement Boolean Whether consent to shipping addresses is required. X

* Deprecated 'has_shipping_addresses' that indicates whether the user retains the shipping addreses. Instead, use '${FIELD_NAME}_needs_agreement' that covers whether the user is required to consent to the scope.

shipping_addresses
Name Type Description Required
id Long Shipping address ID. O
name String Shipping address name. X
is_default Boolean Whether the shipping address is a default address or not. O
updated_at Integer The time when a user updated the shipping address. X
type String Shipping address type.
OLD (Administrative address) or NEW (Road name address) type of address.
X
base_address String Base address that is automatically input when searching for a zipcode. X
detail_address String Detailed address that a user adds to the base address. X
receiver_name String Recipient name. X
receiver_phone_number1 String Recipient phone number. X
receiver_phone_number2 String Additional recipient phone number. X
zone_number String New type of 5-digit postal code for a road name address system.
Required for the road name address system.
X
zip_code String Old type of 6-digit postal code for an administrative address system.
Optional for the administrative address system since some old type of addresses may not have a zip code.
X
Sample
Request: Using Access Token
curl -v -X GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
Request: Using Admin Key
curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=${USER_ID}"
Response
{
  "user_id": 9876543211234,
  "shipping_addresses": [
    {
      "id": 319,
      "name": "Work",
      "is_default": true,
      "updated_at": 1538448856,
      "type": "NEW",
      "base_address": "경기 성남시 분당구 판교역로 231 (삼평동, 에이치스퀘어 에스동)",
      "detail_address": "6층",
      "receiver_name": "판교",
      "receiver_phone_number1": "031-123-2345",
      "receiver_phone_number2": "",
      "zone_number": "13494",
      "zip_code": "463-400"
    },
    {
      "id": 320,
      "name": "회사",
      "is_default": false,
      "updated_at": 1538450389,
      "type": "OLD",
      "base_address": "경기 성남시 분당구 삼평동 680 (삼평동, 에이치스퀘어 에스동)",
      "detail_address": "6층",
      "receiver_name": "판교2",
      "receiver_phone_number1": "010-0056-1234",
      "receiver_phone_number2": "",
      "zone_number": "13494",
      "zip_code": "463-400"
    }
  ],
  "shipping_addresses_needs_agreement": false
}

Android Login required

Before you begin

To use this API on Android, add the v2-user module that provides UserApiClient in the module-level build.gradle file by referring to Add modules.

How to implement

Call the shippingAddresses() method defined in the UserApiClient class. You can also use the following parameters.

Name Type Description Required
fromUpdatedAt Date If multiple shipping addresses are returned through multiple pages, only the shipping addresses that are changed after updated_at time return.
The last shipping address on the previous page is used for an input value for the next page.
If set to 0, shipping addresses are retrieved from the beginning.
X
pageSize Int Number of (two or more) shipping addresses displayed on a page.
(Default: 10)
X
Kotlin
RxKotlin
// Retrieve shipping address with requesting additional consent
UserApiClient.instance.shippingAddresses { userShippingAddresses, error ->
    if (error != null) {
        Log.e(TAG, "Failed to retrieve shipping address", error)
    }
    else if (userShippingAddresses != null) {
        if (userShippingAddresses.shippingAddresses != null) {
            Log.i(TAG, "Succeeded in retrieving shipping addresses" +
                    "\nService user ID: ${userShippingAddresses.userId}" +
                    "\nShipping addresses: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
        }
        else if (userShippingAddresses.needsAgreement == false) {
            Log.e(TAG, "User account does not have a shipping address. If required, select 'Provision after collecting information' option in [My Application] > [Kakao Login] > [Consent items].")
        }
        else if (userShippingAddresses.needsAgreement == true) {
            Log.d(TAG, "You must obtain consent to providing shipping address from a user.")

            val scopes = listOf("shipping_address")

            // Request consent to providing shipping address 
            UserApiClient.instance.loginWithNewScopes(context, scopes) { token, error ->
                if (error != null) {
                    Log.e(TAG, "Failed to get consent to providing shipping address", error)
                }
                else if (token != null) {
                    Log.d(TAG, "allowed scopes: ${token.scopes}")

                    // Retry the request retrieving shipping address
                    UserApiClient.instance.shippingAddresses { userShippingAddresses, error ->
                        if (error != null) {
                            Log.e(TAG, "Failed to retrieve shipping address", error)
                        }
                        else if (userShippingAddresses != null) {
                            Log.i(TAG, "Succeeded in retrieving shipping addresses" +
                                    "\nService user ID: ${userShippingAddresses.userId}" +
                                    "\nShipping addresses: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
                        }
                    }
                }
            }
        }
    }
}
var disposables = CompositeDisposable()

// Retrieve shipping address with requesting additional consent
UserApiClient.rx.shippingAddresses()
    .flatMap { userShippingAddresses ->
        if (userShippingAddresses.needsAgreement == true) {
            Log.d(TAG, "You must obtain consent to providing shipping address from a user.")

            // If InsufficientScope error occurs
            Single.error(ApiError.fromScopes(listOf("shipping_address")))
        }
        else {
            Single.just(userShippingAddresses)
        }
    }
    .retryWhen(
        //  Retry the request the Retrieving shipping address API after requesting additional consent to resolve the InsufficientScope error.
        RxAuthOperations.instance.incrementalAuthorizationRequired(context)
    )
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ userShippingAddresses ->
        if (userShippingAddresses.shippingAddresses != null) {
            Log.i(TAG, "Succeeded in retrieving shipping addresses" +
                    "\nService user ID: ${userShippingAddresses.userId}" +
                    "\nShipping addresses: \n${userShippingAddresses.shippingAddresses?.joinToString("\n")}")
        } else {
            Log.e(TAG, "User account does not have a shipping address. If required, select 'Provision after collecting information' option in [My Application] > [Kakao Login] > [Consent items].")
        }
    }, { error ->
        Log.e(TAG, "Failed to retrieve shipping address", error)
    })
    .addTo(disposables)

If the request succeeds, the response returns through the UserShippingAddresses object that contains a list of ShippingAddress. For more details of ShippingAddress, refer to API Reference and the response of Web.

Legacy Android Login required

Before you begin

To use this API on the Legacy Android,

  • A user must be in a logged-in state.
  • You must add the usermgmt module by referring to Install SDK.
How to implement

Call the shippingAddresses() method defined in the UserManagement class of the com.kakao.usermgmt package.

The response is the same as the response of the Web. Refer to the Response of Web for more details of the response.

UserManagement.getInstance().shippingAddresses(new
ApiResponseCallback<ShippingAddressResponse>() {
  @Override
  public void onSessionClosed(ErrorResult errorResult) {
    // Login is required.
  }

  @Override
  public void onFailure(ErrorResult errorResult) {
  }

  @Override
  public void onSuccess(ShippingAddressResponse result) {
    if (result.shippingAddresses != null) {
      // Succeeded in retrieving shipping addresses 
    } else if (result.shippingAddressNeedsAgreement()) {
      // Request additional consent to retrieve shipping address. 
    } else {
      // If impossible to get the shipping address for a user 
    }
  }
});

iOS Login required

Before you begin

To use this API on iOS,

  • Add the KakaoSDKAuth(Kakao Login module) and KakaoSDKUser(User Management module that provides UserApi) in the Podfile by referring to Install SDK.
  • Add the import statements for the Kakao Login and the User Management modules.

Call this API with the access token issued after a user logs in.

Swift
RxSwift
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKAuth
import RxKakaoSDKAuth

import KakaoSDKUser
import RxKakaoSDKUser
How to implement

Call the shippingAddresses() method defined in the UserApi class. You can also use the following parameters.

Name Type Description Required
fromUpdatedAt Date If multiple shipping addresses are returned through multiple pages, only the shipping addresses that are changed after updated_at time return.
The last shipping address on the previous page is used for an input value for the next page.
If set to 0, shipping addresses are retrieved from the beginning.
X
pageSize Int Number of (two or more) shipping addresses displayed on a page.
(Default: 10)
X
Swift
RxSwift
UserApi.shared.shippingAddresses {(shippingAddress, error) in
    if let error = error {
        print(error)
    }
    else {
        print("shippingAddresses() success.")
        // Do something
        _ = shippingAddress
    }
}
// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.shippingAddresses()
    .subscribe(onSuccess:{ (shippingAddress) in
        print("shippingAddresses() success.")

        // Do something
        _ = shippingAddress               
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

If the request succeeds, the response returns through the UserShippingAddresses object that contains a list of ShippingAddress. For more details of ShippingAddress, refer to API Reference and the response of Web.

Legacy iOS Login required

Before you begin

To use this API on the Legacy iOS,

  • You must implement Kakao Login beforehand.
  • A user has been logged in with a Kakao Account.
How to implement

Call the shippingAddressTask() method to request a shipping address.

The response is the same as the response of the Web. Refer to the Response of Web for more details of the response.

KOSessionTask.shippingAddressTask(completionHandler: { (userShippingAddress, error) in
  if let userShippingAddress = userShippingAddress {
    if let shippingAddresses = userShippingAddress.shippingAddresses {
      // Success to retrieve shipping addresses
    } else if userShippingAddress.shippingAddressNeedsAgreement {
      // Request additional consent to retrieve shipping address. 
      KOSession.shared()?.updateScopes(["shipping_address"], completionHandler: { (error) in
        if let error = error as NSError? {
          if error.code == KOErrorCancelled.rawValue {
            // If a user refuses to provide a shipping address
          } else {
            // Other errors
          }
        } else {
          // If a user consents to providing a shipping address,
          // possible to get shipping addresses when requesting this API 
        }
      })
    } else {
      // If impossible to get the shipping address for a user 
    }
  }
})

Flutter Login required

Before using the Flutter SDK, you must complete the prerequisites.

To retrieve a user's shipping addresses, call the shippingAddresses() method defined in the UserApi class. You can also pass the following parameters.

Parameter
Name Type Description Required
fromUpdatedAt Int If multiple shipping addresses are returned through multiple pages, only the shipping addresses that are changed after fromUpdateAt time return.
The last shipping address on the previous page is used for an input value for the next page.
If set to 0, shipping addresses are retrieved from the beginning.
X
pageSize Int Number of (two or more) shipping addresses displayed on a page.
(Default: 10)
X
Sample
UserShippingAddresses userShippingAddress;
try {
  userShippingAddress = await UserApi.instance.shippingAddresses();
} catch (e) {
  print('Failed to retrieve shipping address.');
  return;
}

if (userShippingAddress.shippingAddresses != null) {
  print('Succeeded in retrieving shipping addresses. \nService user ID: ${userShippingAddress.userId}\nShipping addresses: \n${userShippingAddress.shippingAddresses?.join('\n')}');
} else if (!userShippingAddress.needsAgreement) {
  print('User account does not have a shipping address. If required, select [Provision after collecting information] option in [My Application] > [Kakao Login] > [Consent items]');
} else if (userShippingAddress.needsAgreement) {
  print('You must obtain consent to providing shipping address from a user.');

  List<String> scopes = ['shipping_address'];

  // Request consent to providing shipping addresses
  OAuthToken token;
  try {
    token = await UserApi.instance.loginWithNewScopes(scopes);
    print('allowed scopes: ${token.scopes}');
  } catch (e) {
    print('Failed to get consent to providing shipping address.');
  }

  try {
    UserShippingAddresses userShippingAddresses = await UserApi.instance.shippingAddresses();
    print('Succeeded in retrieving shipping address. \nService user ID: ${userShippingAddresses.userId}\n${userShippingAddresses.shippingAddresses?.join('\n')}');
  } catch (e) {
    print('Failed to retrieve shipping address.');
  }
}
Return data

shippingAddresses() returns the UserShippingAddresses object.

UserShippingAddresses
Name Type Description Required
userId Int Service user ID of a user who requested shipping addresses. X
shippingAddresses List<ShippingAddress> List of shipping addresses. X
needsAgreement Bool Whether consent to shipping addresses is required. O
ShippingAddress
Name Type Description Required
id Int Shipping address ID. O
name String Shipping address name. X
isDefault Bool Whether the shipping address is a default address or not. O
updatedAt DateTime The time when a user updated the shipping address. X
type String Shipping address type.
- OLD: Administrative address
- NEW : Road name address.
X
baseAddress String Base address that is automatically input when searching for a zipcode. X
detailAddress String Detailed address that a user adds to the base address. X
receiverName String Recipient name. X
receiverPhoneNumber1 String Recipient phone number. X
receiverPhoneNumber2 String Additional recipient phone number. X
zoneNumber String New type of 5-digit postal code for a road name address system.
Required for the road name address system.
X
zipCode String Old type of 6-digit postal code for an administrative address system.
Optional for the administrative address system since some old type of addresses may not have a zip code.
X

See more

Web

Android

iOS