# Checking out guest and registered customers

A [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `customerId` references the [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)making the purchase. You can pass this identifier in both [create ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1)and [update checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id) requests.

{% hint style="success" %}
For more information, refer to [sequencing the checkout process](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#sequencing-the-checkout-process) on the [Building checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) page.
{% endhint %}

If you want to process a [guest checkout](#guest-checkouts-or-invoices), then don't set `customerId`. Conversely, if you want to process a [registered checkout](#registered-checkouts-or-invoices), then you should set `customerId`.

## Guest checkouts <a href="#guest-checkouts-or-invoices" id="guest-checkouts-or-invoices"></a>

If you don't set a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `customerId`, then no [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)is associated with the purchase. So, when you want to checkout a guest, don't send `customerId` in the body of a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) or [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request.

In guest checkout scenarios, you'll need to acquire a customer's shipping address (assuming the cart contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital)), billing address, and email address. In addition, you must create one or more payment [sources](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), and when [required](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#missing-tax-identifier-notifications), you'll also need to create a [tax identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers).

Once you obtain these addresses and create these resources, you must associate their data with the checkout.

| Guest customer          |       | Checkout            |
| ----------------------- | :---: | ------------------- |
| Shipping details        | **➔** | `shipTo`            |
| Billing details         | **➔** | `billTo`            |
| Email address           | **➔** | `email`             |
| Tax identifiers         | **➔** | `taxIdentifiers[]`  |
| Business or individual? | **➔** | `type`              |
| Payment method(s)       | **➔** | `payment.sources[]` |

For more information refer to:

* [Address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#address-requirements-and-validations) on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page
* [Creating sources ](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources)and [attaching sources to checkouts](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts) on the [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) page
* [Creating tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#creating-tax-identifiers) and [attaching tax identifiers to checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#attaching-tax-identifiers-to-checkouts-and-invoices) on the [Tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers) page

## Registered checkouts <a href="#registered-checkouts-or-invoices" id="registered-checkouts-or-invoices"></a>

When [checking out](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) a registered customer, make sure you send `customerId` in the body of a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) or [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request. This associates the referenced [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)with the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

When developing registered checkout flows, you should be aware of (1) [what attributes customers and checkouts have in common](#common-attributes) and (2) [how customer data can be passed to the checkout](#passing-customer-data-to-checkouts).

### Common attributes

[Customers ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)and [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)have some common attributes. In registered checkouts, the following data in a customer can be passed to a checkout. The options for [passing this customer data to checkouts](#passing-customer-data-to-checkouts) are version-dependent.

| Customer           |       | Checkout            |
| ------------------ | :---: | ------------------- |
| `shipping`         | **➔** | `shipTo`            |
| `sources[].owner`  | **➔** | `billTo`            |
| `sources[]`        | **➔** | `payment.sources[]` |
| `taxIdentifiers[]` | **➔** | `taxIdentifiers[]`  |
| `locale`           | **➔** | `locale`            |
| `email`            | **➔** | `email`             |
| `customerType`     | **➔** | `type`              |

For more information refer to:

* [Address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#address-requirements-and-validations) on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page
* [Creating sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources), [authenticating sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#authenticating-sources), [saving sources to customers](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers), and [attaching sources to checkouts](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts) on the [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) page
* The [Tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers) page

### Passing customer data to checkouts

In registered checkouts, the [Digital River APIs version](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/versioning) you're using determines how customer data can be passed to checkouts:

#### Version `2021-12-13` and later

In versions `2021-12-13` and later, when you associate a [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)with a [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), Digital River doesn't, by default, pass that customer's data to the checkout. In other words, undefined [common attributes](#common-attributes) in a checkout are not populated with the customer's data.

Instead, once registered customers have signed on to your site, and you've obtained their unique identifier, you can make a [`GET /customers/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers#customers-id) request to retrieve their shipping address, saved payment sources, billing addresses associated with those sources, tax identifiers, and other personal information.

You can present this saved information to customers as an available option at each stage of the checkout process. Whether customers select the saved option presented to them or use your site's forms to enter new information, you must pass this data to the checkout.

For example, when obtaining a ship to address in a checkout that contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), you can get the customer's `shipping`, display it as an available option, and ask customers whether they want to use this saved address. Regardless of whether customers select the saved address or enter a new address, you must set the checkout's `shipTo`.

#### Version `2021-03-23` and earlier

In versions `2021-03-23` and earlier, when you associate a [customer ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)with a [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), Digital River, by default, passes the customer's data to the checkout. In other words, any undefined [common attribute](#common-attributes) in the checkout is automatically inherited from the associated customer.

The only exception is `taxIdentifiers[]`. Unless applicable to the transaction, we don't pass any of a customer's `taxIdentifiers[]` to the checkout. For more information, refer to [using tax identifiers in registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#using-tax-identifiers-in-registered-checkouts) on the [Tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers) page.

{% hint style="info" %}
Data you set in the [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)takes precedence over inherited [customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers) data. Additionally, any data inherited by default from the customer can be overwritten in subsequent [update checkout requests](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1).
{% endhint %}

For example, the following [create checkout request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) contains a `customerId` but doesn't specify `email`, `shipTo`, `billTo`, `locale`, `customerType`, `taxIdentifiers[]` or `sourceId`.

{% tabs %}
{% tab title="POST/checkouts" %}

```
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "currency": "USD",
    "customerId": 531718920336,
    "taxInclusive": false,
    "shipFrom": {
        "address": {
            "country": "US"
        }
    },
    "shippingChoice": {
        "amount": 5,
        "description": "standard",
        "serviceLevel": "SG"
    },
    "items": [
        {
            "skuId": "25b3f1cf-a6d0-439a-b8e6-7e506452f717",
            "quantity": 2,
            "price": 10
        }
    ]
}'
```

{% endtab %}
{% endtabs %}

Once you submit this request, Digital River determines what [common attributes](#common-attributes), if any, are undefined in the checkout, whether the associated customer contains any of these undefined attributes, and, if it does, retrieves that data and sends it to the checkout.

In this particular example, Digital River uses the customer's `email`, `shipping`, `defaultSourceId`, `locale`, and `type` to set the corresponding [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)attributes. Note that the `owner.address`, `owner.firstName`, `owner.lastName`, and `owner.email` in the customer's [default payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#setting-the-default-payment-source) are used to populate the checkout's `billTo`.

{% tabs %}
{% tab title="Customer" %}

```javascript
{
    "id": "531718920336",
    "createdTime": "2021-04-12T20:39:42Z",
    "email": "jdoe@digitalriver.com",
    "shipping": {
        "address": {
            "line1": "123 Boulevard",
            "city": "Saint Paul",
            "postalCode": "55155",
            "state": "MN",
            "country": "US"
        },
        "name": "John Doe",
        "phone": "555-555-5555"
    },
    "defaultSourceId": "5349c370-6694-45ff-915a-882e9b62b48d",
    "sources": [
        {
            "id": "5349c370-6694-45ff-915a-882e9b62b48d",
            "createdTime": "2021-04-12T20:40:26Z",
            "type": "creditCard",
            "reusable": true,
            "state": "chargeable",
            "owner": {
                "firstName": "William",
                "lastName": "Brown",
                "email": "null@digitalriver.com",
                "address": {
                    "line1": "10381 Bren Rd W",
                    "city": "Minnetonka",
                    "postalCode": "55343",
                    "state": "MN",
                    "country": "US"
                }
            },
            "clientSecret": "5349c370-6694-45ff-915a-882e9b62b48d_65525173-9ad9-4339-ba97-f889daf435c6",
            "creditCard": {
                "brand": "Visa",
                "expirationMonth": 7,
                "expirationYear": 2027,
                "lastFourDigits": "1111"
            }
        }
    ],
    "enabled": true,
    "requestToBeForgotten": false,
    "locale": "en_US",
    "type": "individual",
    "liveMode": false
}
```

{% endtab %}

{% tab title="Checkout" %}

```javascript
{
    "id": "37a9569d-b23f-4d3e-b967-8dacb3427cc9",
    "createdTime": "2021-04-12T20:43:18Z",
    "customerId": "531718920336",
    "currency": "USD",
    "email": "jdoe@digitalriver.com",
    "shipTo": {
        "address": {
            "line1": "123 Boulevard",
            "city": "Saint Paul",
            "postalCode": "55155",
            "state": "MN",
            "country": "US"
        },
        "name": "John Doe",
        "phone": "555-555-5555"
    },
    "shipFrom": {
        "address": {
            "country": "US"
        }
    },
    "billTo": {
        "address": {
            "line1": "10381 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "William Brown",
        "email": "null@digitalriver.com"
    },
    "totalAmount": 26.97,
    "subtotal": 25.0,
    "totalFees": 0.0,
    "totalTax": 1.97,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 5.0,
    "items": [
        {
            "id": "3a1fc426-87fb-4216-8619-2d29ac2d5818",
            "skuId": "25b3f1cf-a6d0-439a-b8e6-7e506452f717",
            "amount": 20.0,
            "quantity": 2,
            "tax": {
                "rate": 0.07875,
                "amount": 1.58
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "shippingChoice": {
        "amount": 5.0,
        "description": "standard",
        "serviceLevel": "SG",
        "taxAmount": 0.39
    },
    "updatedTime": "2021-04-12T20:43:18Z",
    "locale": "en_US",
    "customerType": "individual",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "liveMode": false,
    "payment": {
        "sources": [
            {
                "id": "5349c370-6694-45ff-915a-882e9b62b48d",
                "type": "creditCard",
                "amount": 26.97,
                "owner": {
                    "firstName": "William",
                    "lastName": "Brown",
                    "email": "null@digitalriver.com",
                    "address": {
                        "line1": "10381 Bren Rd W",
                        "city": "Minnetonka",
                        "postalCode": "55343",
                        "state": "MN",
                        "country": "US"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            }
        ],
        "session": {
            "id": "55b44240-577c-4485-af5a-2c8224cb6653",
            "amountContributed": 26.97,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "55b44240-577c-4485-af5a-2c8224cb6653_87c01674-8312-4f3a-afc7-7b2714fd47e8"
        }
    }
}
```

{% endtab %}
{% endtabs %}