---
title: "Create a Fully Hosted Session"
method: POST
path: "/api/sessions/"
tags: ["Fully Hosted Sessions"]
---

# Create a Fully Hosted Session

`POST /api/sessions/`

A `POST` request to `/sessions/` initiates a `Session` of the Fully Hosted Forage Checkout UI. On success, the API creates a Forage [`Order`](https://docs.joinforage.app/reference/orders).

The response payload represents the [Fully Hosted `Session`](https://docs.joinforage.app/reference/forage-sessions#fully-hosted-session). The `ref` and `redirect_url` fields are the most important:
  - `ref` represents the `Order`
    - Store this `ref` so that you can pass it in a future request to [Retrieve the Order](https://docs.joinforage.app/reference/create-order) outcome
  - `redirect_url` is the URL that launches the customer-facing Forage Session UI
    - Point customers to this URL when they’re ready to complete checkout

## Important Fully Hosted Session parameters

### Pass the `tax_rate` of every item in the `product_list` so that Forage can handle taxes

Forage calculates the taxes for the `Order` depending on how the customer decides to pay. SNAP eligible items are only subject to taxes when purchased with a credit/debit card, per FNS regulations. [Retrieve the Order](https://docs.joinforage.app/reference/get-order) outcome and inspect the `sales_tax_applied` response value to find the final tax amount charged to the customer, or review the `taxes_charged` on a per item level in the `product_list` field.

### Pass `customer_id` to speed up the request and prefill stored payment methods

`customer_id` helps Forage's servers more quickly identify and associate the correct customer with the Session. While `customer_id` is not technically a required parameter, if you omit it then requests could take longer to process. **It is strongly recommended to pass `customer_id`.**

When the same `customer_id` is provided for a returning customer, Forage will retrieve and reuse their stored payment method, if available. Alternatively, passing the same `ebt_payment_method` can also pre-fill the stored payment method in the checkout session.

Each customer should only have one unique `customer_id`. For example, if you create both a Forage Session and a `PaymentMethod` for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods.

See these guides for additional information:

- [How Forage Fully Hosted integrations work](https://docs.joinforage.app/docs/fully-hosted#how-it-works)
- [Fully Hosted Quickstart](https://docs.joinforage.app/docs/fully-hosted-quickstart)
- [Fully Hosted `Session` payload](https://docs.joinforage.app/reference/forage-sessions#fully-hosted-session)

## Request body

- FullyHostedSessionRequest — This object starts a Forage Session, an instance of the ready-to-use Forage Checkout UI. It either initiates a Custom Capture Session, if passed as is to the /capture_sessions/ endpoint, or a Fully Hosted Session, if passed to the /sessions/ endpoint. Refer to each endpoint's documentation for details.
  - `success_redirect_url` string, required — The URL that Forage should redirect your customer to if the `Order` is completed successfully.
  - `cancel_redirect_url` string, required — The URL that Forage should redirect your customer to if the `Order` is cancelled.
  - `delivery_address` DeliveryAddressData, required — ⚠️ **Exception**: If the purchase is made in-store via a POS Terminal, then a `delivery_address` is not required when creating a `Payment`. The address for delivery or pickup of the `Order`. Per FNS regulations, this value must always be provided. If the `Order` is for pickup, then use the merchant address.
    - `city` string — The name of the city.
    - `country` string — Either `us` or `US`. Defaults to `US` if not provided.
    - `line1` string, required — The first line of the street address.
    - `line2` string, nullable — The second line of the street address.
    - `zipcode` string, required — The zip or postal code.
    - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state.
  - `is_delivery` boolean — Whether the order is for delivery or pickup. Optional — defaults to `false`. Forage reports this value to FNS for regulatory purposes.
  - `is_commercial_shipping` boolean, nullable — Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
  - `supported_benefits` string[] — A list that limits the types of payment methods that can be applied at checkout, including any or all of the values in: `["snap", "ebt_cash", "non_ebt"]`. Use `supported_benefits` **only** if you want to restrict the possible payment method types. Omit this field in all other cases. For example, pass `["snap", "non_ebt"]` if you want to accept SNAP and credit card payments only (excluding EBT Cash).
  - `platform_fee` number — An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee.
  - `customer_id` string — **⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.** A unique identifier for the end customer making the payment. Forage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. **It is strongly recommended to pass customer_id.** If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage `Session` (Fully Hosted or Custom) or `Payment` (SDK) for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods.
  - `external_order_id` string — A unique identifier for the order as created by the merchant or platform (not Forage). When a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the `Order`. This field enables merchants to map order IDs in their system to corresponding Forage `Order` IDs. **You must build with Forage Version `2023-05-15` or later to use `external_order_id`.** Either pass `2023-05-15` as the `API-Version` header on a per request basis, or set the version for all requests in the Forage dashboard.
  - `external_location_id` string — A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order.
  - `product_list` ProductData[], required — A list of products in the customer's cart at checkout. > ⚠️ Required Fields > > Each item must include the following **required** fields: > > - `name` > - `upc` > - `unit_price` > - `quantity` > - `eligibility` If there are no taxes applied to any of the products, then you can pass an empty array as the value. _This field is returned as `null` in the case of a Custom `Session`_.
    - `name` string, required — The name of the product.
    - `upc` string — The UPC of the product.
    - `gtin` string — The GTIN (Global Trade Item Number) of the product.
    - `unit_price` number, required — The unit price of the product.
    - `quantity` number — The quantity of the product.
    - `tax_rate` number — The tax rate for the product, represented as a decimal with at most six decimal places. A value of `0` indicates a tax rate of 0%, and a value of `1` indicates a tax rate of 100%. To set a 2% tax rate, for example, set the value to `0.02`. Use this field if the product is subject to only one tax rate. If multiple tax rates apply, for example both a state grocery tax and a sweetened beverage tax, then use the `tax_rate_list` param instead of `tax_rate`.
    - `tax_rate_list` object[]
      - `imposed_by` string, required — The entity applying the tax to this item.
      - `tax_rate` number, required — The tax rate applied to the item by the entity described in the `imposed_by` field. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`.
      - `taxes_charged` number — The portion of taxes charged for this item attributable to the `imposed_by` entity.
      - `taxes_exempted` number — The portion of taxes exempted for this item attributable to the `imposed_by` entity.
    - `taxes_charged` number — The amount of taxes charged for this item in USD.
    - `taxes_exempted` number — The amount of taxes exempted for this item in USD.
    - `tax_total` number — The total tax for this item in USD.
    - `eligibility` 'snap' | 'ebt_cash' | 'non_ebt' — The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`.
  - `psp_customer_id` string — The third-party payment processor's unique identifier for the customer. An optional field passed in anticipation of a customer applying a credit/debit card to an `Order` balance. _This field is returned as `null` in the case of a Custom `Session`_. **You must build with Forage Version `2023-05-15` or later to use `psp_customer_id`.** Either pass `2023-05-15` as the `API-Version` header on a per request basis, or set the version for all requests in the Forage dashboard.
  - `ebt_payment_method` string — A unique reference hash for an existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods). Use this param if you'd like to pre-populate the payment method field in the checkout UI for a returning customer. _This field is only returned in the response if it is passed in the original request body_.

## Response `200`

__OK__ - Success

- FullyHostedSessionResponse — The response payload represents a Fully Hosted Forage `Session`, an instance of the ready-to-use Forage Checkout UI.
  - `ref` string, required — A unique reference hash for the `Order` created for this `Session`.
  - `snap_total` string, currency, required — The SNAP eligible portion of the order cost in USD, represented as a numeric string. Precision is supported to the penny.
  - `ebt_cash_total` string, currency, required — The portion of the `Order` total, in USD, that is EBT Cash eligible only, represented as a numeric string. Precision is supported to the penny.
  - `remaining_total` string, currency, required — The portion of the `Order` total, in USD, that is neither SNAP eligible nor EBT Cash eligible, represented as a numeric string. This amount must be charged to a credit or debit card, with precision supported to the penny.
  - `product_list` ProductDataResponse[], required — A list of products in the customer's cart at checkout. > ⚠️ Required Fields > > Each item must include the following **required** fields: > > - `name` > - `upc` > - `unit_price` > - `quantity` > - `eligibility` If there are no taxes applied to any of the products, then you can pass an empty array as the value. _This field is returned as `null` in the case of a Custom `Session`_.
    - `id` integer, required — The unique identifier for the product.
    - `name` string, required — The name of the product.
    - `upc` string, nullable, required — The UPC of the product.
    - `gtin` string — The GTIN (Global Trade Item Number) of the product.
    - `unit_price` string, currency, required — The unit price of the product, represented as a numeric string.
    - `quantity` integer, required — The quantity of the product.
    - `tax_rate` string, decimal — The tax rate for the product, represented as a decimal string with at most six decimal places. A value of `0` indicates a tax rate of 0%, and a value of `1` indicates a tax rate of 100%. To set a 2% tax rate, for example, set the value to `0.02`. Use this field if the product is subject to only one tax rate. If multiple tax rates apply, for example both a state grocery tax and a sweetened beverage tax, then use the `tax_rate_list` param instead of `tax_rate`.
    - `tax_rate_list` object[]
      - `imposed_by` string, required — The entity applying the tax to this item.
      - `tax_rate` string, decimal, required — The tax rate applied to the item by the entity described in the `imposed_by` field, represented as a decimal string. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`.
      - `taxes_charged` string, currency, nullable — The portion of taxes charged for this item attributable to the `imposed_by` entity, represented as a numeric string.
      - `taxes_exempted` string, currency, nullable — The portion of taxes exempted for this item attributable to the `imposed_by` entity, represented as a numeric string.
    - `eligibility` 'snap' | 'ebt_cash' | 'non_ebt', nullable, required — The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`.
    - `snap_amount` string, currency, nullable, required — The amount paid for this product using SNAP benefits in USD, represented as a numeric string. Precision is supported to the penny.
    - `cash_amount` string, currency, nullable, required — The amount paid for this product using EBT Cash benefits in USD, represented as a numeric string. Precision is supported to the penny.
    - `credit_debit_amount` string, currency, nullable, required — The amount paid for this product using credit or debit card in USD, represented as a numeric string. Precision is supported to the penny.
    - `tax_collected` string, currency, nullable, required — The tax amount collected for this product in USD, represented as a numeric string. Precision is supported to the penny.
    - `taxes_charged` string, currency, nullable, required — The amount of taxes charged for this product in USD, represented as a numeric string. Precision is supported to the penny.
    - `taxes_exempted` string, currency, nullable, required — The amount of taxes exempted for this product in USD, represented as a numeric string. Precision is supported to the penny.
  - `platform_fee` string, decimal — An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee. Represented as a decimal string.
  - `delivery_address` DeliveryAddressData, required — ⚠️ **Exception**: If the purchase is made in-store via a POS Terminal, then a `delivery_address` is not required when creating a `Payment`. The address for delivery or pickup of the `Order`. Per FNS regulations, this value must always be provided. If the `Order` is for pickup, then use the merchant address.
    - `city` string — The name of the city.
    - `country` string — Either `us` or `US`. Defaults to `US` if not provided.
    - `line1` string, required — The first line of the street address.
    - `line2` string, nullable — The second line of the street address.
    - `zipcode` string, required — The zip or postal code.
    - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state.
  - `is_delivery` boolean, required — Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to `false` if not provided.
  - `success_redirect_url` string, required — The URL that Forage should redirect your customer to if the `Order` is completed successfully.
  - `cancel_redirect_url` string, required — The URL that Forage should redirect your customer to if the `Order` is cancelled.
  - `supported_benefits` string[], required — A list that limits the types of payment methods that can be applied at checkout, including any or all of the values in: `["snap", "ebt_cash", "non_ebt"]`. Use `supported_benefits` **only** if you want to restrict the possible payment method types. Omit this field in all other cases. For example, pass `["snap", "non_ebt"]` if you want to accept SNAP and credit card payments only (excluding EBT Cash).
  - `psp_customer_id` string, nullable, required — The third-party payment processor's unique identifier for the customer. An optional field passed in anticipation of a customer applying a credit/debit card to an `Order` balance. _This field is returned as `null` in the case of a Custom `Session`_. **You must build with Forage Version `2023-05-15` or later to use `psp_customer_id`.** Either pass `2023-05-15` as the `API-Version` header on a per request basis, or set the version for all requests in the Forage dashboard.
  - `customer_id` string, required — **⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.** A unique identifier for the end customer making the payment. Forage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. **It is strongly recommended to pass customer_id.** If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage `Session` (Fully Hosted or Custom) or `Payment` (SDK) for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods.
  - `external_order_id` string, required — A unique identifier for the order as created by the merchant or platform (not Forage). When a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the `Order`. This field enables merchants to map order IDs in their system to corresponding Forage `Order` IDs. **You must build with Forage Version `2023-05-15` or later to use `external_order_id`.** Either pass `2023-05-15` as the `API-Version` header on a per request basis, or set the version for all requests in the Forage dashboard.
  - `external_location_id` string, nullable, required — A unique identifier for the physical fulfillment location.
  - `status` 'draft' | 'processing' | 'failed' | 'succeeded' | 'canceled', required — The status is always `draft` at the start.
  - `success_date` string, date-time, nullable, required — A UTC timestamp that indicates when all of the `Payments` associated with the `Order` are successfully charged, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.
  - `receipt` ReceiptData, required — Most of the information that you're required to display to the customer, according to FNS regulations. This field is `null` if the data that populates the receipt is not yet available. The total amount paid by the customer is `snap_amount` + `ebt_cash_amount` + `other_amount`. This amount will be settled with the merchant after applying Forage's fees.
    - `ref_number` string — A unique reference hash for the Forage `Order`, `Payment`, or `Refund` associated with this receipt. Note: `receipt.ref_number` equals `ref`.
    - `is_voided` boolean — Whether the transaction associated with this receipt has been voided. If `false`, then the transaction finished processing as expected. If `true`, then the transaction was reversed.
    - `snap_amount` string — The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
    - `ebt_cash_amount` string, currency — The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
    - `cash_back_amount` string, currency, nullable — The USD amount of cash back given to the customer, represented as a numeric string.
    - `other_amount` string, currency — The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string.
    - `sales_tax_applied` string, currency — The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
    - `balance` BalanceResponse — An object that represents an EBT cardholder's account balance.
      - `id` integer — The unique identifier for the balance record.
      - `snap` string, currency — The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string.
      - `non_snap` string, currency — The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string.
      - `updated` string, date-time — A UTC timestamp that indicates when the funds in the account last changed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.
      - `sequence_number` string — A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks.
    - `last_4` string — The last four digits of the EBT Card number.
    - `message` string — A message from the EBT payment network that must be displayed to the EBT cardholder.
    - `transaction_type` 'Order' | 'Refund' | 'Payment' — A constant string that is used to identify the transaction type associated with the receipt.
    - `created` string, date-time — A UTC timestamp of when the Forage transaction object was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.
    - `sequence_number` string, nullable — The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions.
  - `expires_at` string, date-time, nullable, required — A UTC timestamp of when the `Order` associated with the `Session` will expire if it is not captured or canceled, set to 30 minutes from when the `Order` is created.
  - `is_commercial_shipping` boolean, nullable, required — Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
  - `redirect_url` string, url, required — The URL that launches the Forage Session UI. Point a customer to this URL when they are ready to complete checkout.
  - `errors` object[], required — An array with information about the error.
    - `code` string — A short string that represents the error.
    - `message` string — A developer-facing message with more details about the error, not to be displayed to customers.
    - `source` object
      - `resource` string — The type of the Forage resource involved in the error.
      - `ref` string — If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved.
    - `details` object — Additional details about the error, if applicable.
  - `ebt_payment_method` string — A unique reference hash for an existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods). Use this param if you'd like to pre-populate the payment method field in the checkout UI for a returning customer. _This field is only returned in the response if it is passed in the original request body_.

## Other responses

- `400` — __Bad request__ - The request was not accepted because of an error in the request body or path.
- `401` — Unauthorized
- `409` — Conflict
- `423` — __Locked__ - The request could not be completed because the target resource is currently locked.
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.dev/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/revisions/4b7212706fae/schema)