> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Hosted checkout URL query parameters

Append query parameters to hosted checkout launch URLs to pass information about a customer and items to a checkout.

---

{% callout type="default" %}
Access to Hosted checkouts on live accounts is limited to approved mobile app companies. It's available on all [sandbox accounts](https://developer.paddle.com/build/tools/sandbox.md) for evaluation and testing. To request approval, contact [sellers@paddle.com](mailto:sellers@paddle.com).
{% /callout %}

You can use [hosted checkouts](https://developer.paddle.com/concepts/sell/hosted-checkout-mobile-apps.md) to let users securely make purchases outside your mobile app. Each hosted checkout has a unique link that you can add to your app to let customers open a checkout that's fully hosted by Paddle.

All hosted checkout URL query parameters are optional. You can set defaults when creating a hosted checkout in **Paddle > Checkout > Hosted Checkouts**, like the prices to open the checkout with if no `priceId` or `transactionId` is passed. However, one is required if no default price is set.

Hosted checkout parameters also work with the [Paddle mobile web payments starter kit](https://github.com/PaddleHQ/paddle-mobile-web-payments-starter), which you can use to deploy your own mobile purchase workflow.

{% callout type="info" %}
For maximum compatibility across browsers, make sure to [percent-encode query strings](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). For example, pass `max%2Bpaddle%40example.com` for `max+paddle@example.com`.
{% /callout %}

## Parameters

```yaml
title: Hosted checkout parameters.
type: object
properties:
  price_id:
    type: string
    examples:
      - pri_01gm81eqze2vmmvhpjg13bfeqg
    description: >-
      Paddle ID of the price for the item that this hosted checkout is for. Pass a comma-separated list of price IDs to
      open a checkout for multiple prices. If omitted and no `transaction_id` is passed, the default prices for the
      hosted checkout are used. Required if no default prices are set and no `transaction_id` is passed.
  discount_code:
    type: string
    examples:
      - BF20OFF
    description: >-
      Discount code to apply. Use to prepopulate a discount at checkout. Takes precedence over `discount_id`. If
      omitted, no discount is applied.
  discount_id:
    type: string
    examples:
      - dsc_01gtf15svsqzgp9325ss4ebmwt
    description: >-
      Paddle ID of a discount to apply. Use to prepopulate a discount at checkout. Ignored if `discount_code` is also
      passed. If omitted, no discount is applied.
  paddle_customer_id:
    type: string
    examples:
      - ctm_01gm82kny0ad1tk358gxmsq87m
    description: >-
      Paddle ID of the customer for this checkout. Use if you know the customer, like if they're authenticated and
      making a change to their subscription. You can't use if you're passing `user_email`.
  user_email:
    type: string
    description: Email for this customer. You can't use if you're passing `paddle_customer_id`.
  country_code:
    type: string
    examples:
      - US
    description: Two-letter ISO 3166 country code for this customer.
  postal_code:
    type: string
    examples:
      - "10021"
    description: ZIP or postal code of the address. Only asked for in countries with postal codes.
  app_user_id:
    type: string
    description: Unique identifier for this customer in RevenueCat. Used for fulfillment using entitlements in RevenueCat.
  transaction_id:
    type: string
    examples:
      - txn_01gp3z8cfkqgdq07hcr3ja0q95
    description: >-
      Paddle ID of an existing transaction. You can create a transaction on your backend and pass to checkout to use,
      instead of passing `price_id` and customer details. If omitted and no `price_id` is passed, the default prices for
      the hosted checkout are used. Required if no default prices are set and no `price_id` is passed.
  locale:
    type: string
    default: (browser default)
    description: Language for the checkout.
    enum:
      - ar
      - zh-Hans
      - zh-TW
      - da
      - nl
      - en
      - fr
      - de
      - it
      - ja
      - ko
      - "no"
      - pl
      - pt
      - pt-BR
      - tr
      - ru
      - es
      - sv
    x-enum-descriptions:
      ar:
        description: Arabic (العربية)
      zh-Hans:
        description: Chinese (Simplified) (简化字)
      zh-TW:
        description: Chinese (Traditional) (正體字)
      da:
        description: Danish (Dansk)
      nl:
        description: Dutch (Nederlands)
      en:
        description: English
      fr:
        description: French (Français)
      de:
        description: German (Deutsch)
      it:
        description: Italian (Italiano)
      ja:
        description: Japanese (日本語)
      ko:
        description: Korean (한국어)
      "no":
        description: Norwegian (Norsk)
      pl:
        description: Polish (Polski)
      pt:
        description: Portuguese (Português)
      pt-BR:
        description: Portuguese (Brazilian) (Português do Brasil)
      tr:
        description: Turkish (Türkçe)
      ru:
        description: Russian (Русский)
      es:
        description: Spanish (Español)
      sv:
        description: Swedish (Svenska)
  theme:
    type: string
    default: light
    description: Theme for the checkout. If omitted, defaults to light.
    enum:
      - light
      - dark
    x-enum-descriptions:
      light:
        description: Light-themed checkout.
      dark:
        description: Dark-themed checkout.
  allowed_payment_methods:
    type: array
    description: Payment options presented to customers at checkout.
    items:
      type: string
      enum:
        - alipay
        - apple_pay
        - bancontact
        - blik
        - card
        - google_pay
        - ideal
        - kakao_pay
        - mb_way
        - naver_pay
        - payco
        - paypal
        - pix
        - samsung_pay
        - south_korea_local_card
        - upi
      x-enum-descriptions:
        alipay:
          description: Alipay, popular in China.
        apple_pay:
          description: Apple Pay on a supported Apple device.
        bancontact:
          description: Bancontact, popular in Belgium.
        blik:
          description: BLIK, a popular payment method in Poland.
        card:
          description: Credit or debit card.
        google_pay:
          description: Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
        ideal:
          description: iDEAL, popular in the Netherlands.
        kakao_pay:
          description: Kakao Pay, a popular payment method in Korea.
        mb_way:
          description: MB WAY, a popular payment method in Portugal.
        naver_pay:
          description: Naver Pay, a popular payment method in Korea.
        payco:
          description: Payco, a popular payment method in Korea.
        paypal:
          description: PayPal.
        pix:
          description: Pix, popular in Brazil. Available in early access.
        samsung_pay:
          description: Samsung Pay, a popular payment method in Korea.
        south_korea_local_card:
          description: Korean local credit or debit card.
        upi:
          description: Unified Payments Interface (UPI), popular in India. Available in early access.
  show_add_tax_id:
    type: boolean
    default: true
    description: Whether the option to add a tax number is displayed at checkout. Defaults to `true`.
```

## Examples

{% accordion %}
{% accordion-item title="Hosted checkout link for an item" %}

This example passes a price ID to Paddle Checkout to specify what the customer is purchasing.

```sh {% wrap=true %}
https://pay.paddle.io/checkout/hsc_01jt8s46kx4nv91002z7vy4ecj_1as3scas9cascascasasx23dsa3asd2a?price_id=pri_01h1vjg3sqjj1y9tvazkdqe5vt
```

{% /accordion-item %}
{% accordion-item title="Hosted checkout link for multiple items" %}

This example passes two price IDs to Paddle Checkout to specify that a customer is purchasing two items.

```sh {% wrap=true %}
https://pay.paddle.io/checkout/hsc_01jt8s46kx4nv91002z7vy4ecj_1as3scas9cascascasasx23dsa3asd2a?price_id=pri_01h1vjg3sqjj1y9tvazkdqe5vt,pri_01hv0vax6rv18t4tamj848ne4d
```

{% /accordion-item %}
{% accordion-item title="Hosted checkout link for an item with a customer email" %}

This example passes a price ID to tell Paddle Checkout what the customer is purchasing, along with a user email address. The email address is [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).

```sh {% wrap=true %}
https://pay.paddle.io/checkout/hsc_01jt8s46kx4nv91002z7vy4ecj_1as3scas9cascascasasx23dsa3asd2a?price_id=pri_01h1vjg3sqjj1y9tvazkdqe5vt&user_email=sam%40example.com
```

{% /accordion-item %}
{% accordion-item title="Hosted checkout link for an item with a discount code" %}

This example passes a price ID to tell Paddle Checkout what the customer is purchasing, along with a discount code.

```sh {% wrap=true %}
https://pay.paddle.io/checkout/hsc_01jt8s46kx4nv91002z7vy4ecj_1as3scas9cascascasasx23dsa3asd2a?price_id=pri_01h1vjg3sqjj1y9tvazkdqe5vt&discount_code=BF20OFF
```

{% /accordion-item %}
{% /accordion %}