--- title: "Get current or create a new cart" method: GET path: "/api/checkout/pub/orderForm" tags: ["Shopping cart"] --- # Get current or create a new cart `GET /api/checkout/pub/orderForm` You can use this request to get your current shopping cart information (`orderFormId`) or to create a new cart. **Important**: To create a new empty shopping cart you need to send this request with the query param `forceNewCart=true`. The [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) is the data structure which represents a shopping cart and contains all information pertaining to it. Hence, the `orderFormId` obtained in response is the identification code of the newly created cart. > This request has a time out of 45 seconds. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Read Shopping Cart** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations. ## Query parameters - `forceNewCart` boolean - `individualShippingEstimates` boolean ## Headers - `Content-Type` string, required - `Accept` string, required ## Response `200` OK - OrderForm — OrderForm object containing cart and order information. - `orderFormId` string — ID of the orderForm corresponding to a specific cart. - `salesChannel` string — Attribute created by the seller, in their VTEX store configuration. - `loggedIn` boolean — Indicates whether the user is logged into the store. - `isCheckedIn` boolean — Indicates whether order is checked in. - `storeId` string, nullable — ID of the store. - `allowManualPrice` boolean — Permission to modify item price manually. - `canEditData` boolean — Data can be edited. - `userProfileId` string, nullable — Unique ID associated with the customer profile. - `profileProvider` string — Profile provider. - `availableAccounts` string[] — Available accounts. - `availableAddresses` object[] — Information on each available address. - `addressType` string — Address type. - `receiverName` string — Name of the receiver. - `addressId` string, nullable — Address ID. - `isDisposable` boolean — Indicates whether the address is disposable. Addresses marked as `isDisposable = true` are not saved to the shopper's profile when the order is completed, while addresses with `isDisposable = false` definitely belong to the shopper. Behavior by address type: - `giftRegistry`, `pickup`, `search`, and `inStore`: always disposable, as they do not belong to the shopper navigating the cart. - `residential`: may be disposable. Addresses from a complete shopper profile, or entered by an authenticated shopper with a complete profile, are not disposable. All other residential addresses are disposable, including those from first-time purchases, since no complete profile exists yet. - `invoice`: does not have the `isDisposable` flag, since invoice addresses are of type `Address` rather than `ShippingAddress`. In practice, only authenticated shoppers can add invoice attachments to the cart, so they are never treated as disposable. - `commercial`: corresponds to company addresses used in B2B contexts and follows the same logic as residential addresses. When a residential address is marked as disposable and the profile is complete, authentication is required to complete the order. Additionally, when a disposable residential address is used to complete a purchase, saved cards cannot be used. - `city` string — City of the address. - `state` string — State of the address. - `country` string — Country of the address. ISO three-letter code. - `street` string — Street of the address. - `number` string — Number of the address. - `neighborhood` string — Neighborhood of the address. - `complement` string, nullable — Complement to the shipping address, in case it applies. - `reference` string, nullable — Reference that may help in the location of the address. - `geoCoordinates` number[] — Array with two strings that represent geocoordinates: first latitude, then longitude. - `userType` string, nullable — User type. - `ignoreProfileData` boolean — Ignore customer profile data. - `value` integer — Total value of the order without separating cents. For example, $24.99 is represented as `2499`. - `messages` string[] — Array containing an object for each message generated by our servers while processing the request. - `items` object[] — Information on each item in the order. - `uniqueId` string — Unique ID. - `id` string — ID of the item. - `productId` string — Product ID. - `productRefId` string — Product Ref ID. - `refId` string, nullable — Ref ID. - `ean` string, nullable — European Article Number. - `name` string — Product name. - `skuName` string — SKU name. - `modalType` string, nullable — Modal type. - `parentItemIndex` integer, nullable — Parent item index. - `parentAssemblyBinding` string, nullable — Parent assembly binding. - `priceValidUntil` string — Price expiration date and time. - `tax` integer — Tax value in cents. - `taxCode` string — A unique identifier code assigned to a tax within the VTEX Admin. - `price` integer — Price in cents. - `listPrice` integer — List price in cents. - `manualPrice` integer, nullable — Manual price in cents. - `manualPriceAppliedBy` string, nullable — User that applied the manual price, if that is the case. - `sellingPrice` integer — Selling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the `priceDefinition` data structure instead. - `rewardValue` integer — Reward value in cents. - `isGift` boolean — Indicates whether item is a gift. - `additionalInfo` object — Additional information. - `dimension` string, nullable — Dimension. - `brandName` string — Brand name. - `brandId` string — Brand ID. - `offeringInfo` string, nullable — Offering information. - `offeringType` string, nullable — Offering type. - `offeringTypeId` string, nullable — Offering type ID. - `preSaleDate` string, nullable — Presale date. - `productCategoryIds` string — Product category IDs. - `productCategories` object — Object, where each field is an ID from `productCategoryIds`. - `{ID}` string — Product category corresponding to the ID in the field key. - `quantity` integer — Quantity. - `seller` string — Seller. - `sellerChain` string[] — Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order. - `imageUrl` string — Image URL. - `detailUrl` string — Detail URL. - `bundleItems` object[] — Information on services sold along with the SKU. Example: a gift package. - `type` string — Service type. - `id` integer — Service identifier. - `name` string — Service name. - `price` integer — Service price in cents. - `attachments` object[] — Array containing information on attachments. - `name` string — Attachment name. - `content` object — Object containing the attachment content as key-value pairs. - `priceTags` object[] — Array of price tags, each of which, modifies the price in some way, like discounts or taxes that apply to the item in the context of the order. - `identifier` string, nullable — Promotion unique identifier. - `isPercentual` boolean — Indicates whether the `value` and `rawValue` of the price tag represent a percentage to be applied during checkout calculation. The default value is `false`. When set to `true`, the `value` and `rawValue` fields are interpreted as percentages, and the final price is calculated accordingly. - `name` string — Price tag name in the format: `{type}@{where}-{identifier}#{calculationId}`. Where: - `type` indicates whether the tag refers to a discount or tax. - `where` specifies the context, either price or shipping. - `identifier` is the promotion ID. - `calculationId` is a hash that may vary with each price calculation. - `rawValue` number — Raw price tag value with up to five decimals, sourced from the promotion configuration. This value is informational only and is not used in checkout calculations. - `value` integer — Price tag value representing either a promotion (value decrease) or a tax (value increase). - `availability` string — Availability. - `measurementUnit` string — Measurement unit. - `unitMultiplier` integer — Unit multiplier. - `manufacturerCode` string, nullable — Manufacturer code. - `priceDefinition` object — Price information for all units of a specific item. - `calculatedSellingPrice` integer — Item's calculated unitary selling price in cents. - `total` integer — Total value for all units of the item in cents. - `sellingPrices` object[] — Array of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total. - `value` integer — Value in cents for that specific rounding. - `quantity` integer — Rounding quantity, meaning how many items are rounded to this value. - `selectableGifts` string[] — Array containing the data of the item selected as a gift. - `totalizers` object[] — Array containing an object for each totalizer for the purchase. Totalizers contain the sum of values for a specific part of the order (e.g. Total item value, Total shipping value). - `shippingData` object, nullable — Shipping information pertinent to the order. - `address` object, nullable — Address information. - `addressType` string — Type of address. For example, `Residential` or `Pickup`. - `receiverName` string, nullable — Name of the person who is going to receive the order. - `addressId` string, nullable — Address ID. - `isDisposable` boolean — Indicates whether the address is disposable. Addresses marked as `isDisposable = true` are not saved to the shopper's profile when the order is completed, while addresses with `isDisposable = false` definitely belong to the shopper. Behavior by address type: - `giftRegistry`, `pickup`, `search`, and `inStore`: always disposable, as they do not belong to the shopper navigating the cart. - `residential`: may be disposable. Addresses from a complete shopper profile, or entered by an authenticated shopper with a complete profile, are not disposable. All other residential addresses are disposable, including those from first-time purchases, since no complete profile exists yet. - `invoice`: does not have the `isDisposable` flag, since invoice addresses are of type `Address` rather than `ShippingAddress`. In practice, only authenticated shoppers can add invoice attachments to the cart, so they are never treated as disposable. - `commercial`: corresponds to company addresses used in B2B contexts and follows the same logic as residential addresses. When a residential address is marked as disposable and the profile is complete, authentication is required to complete the order. Additionally, when a disposable residential address is used to complete a purchase, saved cards cannot be used. - `postalCode` string — Postal code. - `city` string — City of the shipping address. - `state` string — State of the shipping address. - `country` string — Three letter ISO code of the country of the shipping address. - `street` string — Street of the shipping address. - `number` string — Number of the building, house or apartment in the shipping address. - `neighborhood` string — Neighborhood of the shipping address. - `complement` string, nullable — Complement to the shipping address, in case it applies. - `reference` string, nullable — Complement that might help locate the shipping address more precisely in case of delivery. - `geoCoordinates` number[] — Array with two strings that represent geocoordinates: first latitude, then longitude. - `logisticsInfo` object[] — Array with logistics information. Each object in this array corresponds to an object in the `items` array, based on the respective `itemIndex`. - `itemIndex` integer — Index corresponding to the position of the object in the `items` array. - `selectedSla` string, nullable — SLA selected by the customer. If the store uses the [Delivery Options](https://help.vtex.com/en/docs/tutorials/delivery-options-beta) feature, this field returns the delivery option ID selected for this SLA, as the example `1223d5b4-52a4-442f-ab23-01345b60be48`. - `selectedDeliveryChannel` string, nullable — Delivery channel selected by the customer. - `addressId` string, nullable — Address ID. - `slas` object[] — Information on available SLAs. - `id` string — SLA ID. If the store uses the [Delivery Options](https://help.vtex.com/en/docs/tutorials/delivery-options-beta) feature, this field returns the delivery option ID selected for this SLA, as the example `1223d5b4-52a4-442f-ab23-01345b60be48`. - `deliveryChannel` string — Delivery channel. - `name` string — SLA name. If the store uses the [Delivery Options](https://help.vtex.com/en/docs/tutorials/delivery-options-beta) feature, the value of this field will show the specific delivery option name selected for this SLA, as the example `Delivery | BRA | Up to 30 hours`. - `deliveryIds` object[] — Information on each delivery ID. - `courierId` string — Courier ID. - `warehouseId` string — Warehouse ID. - `dockId` string — Warehouse ID. - `courierName` string — Courier name. - `quantity` integer — Quantity. - `attachmentOfferings` object[], nullable — List of attachments details. - `name` string, nullable, required — Name of the attachment. - `required` boolean, nullable, required — Defines if the attachment is required (`true`) or not (`false`). - `schema` object, nullable, required — Custom values [created into attachment](https://help.vtex.com/en/tutorial/adding-an-attachment--7zHMUpuoQE4cAskqEUWScU). - `shippingEstimate` string — Shipping estimate. For instance, "three business days" will be represented as `3bd`. The unit can be `bd` for business days, `d` for days, `h` for hours, or `m` for minutes. - `shippingEstimateDate` string, nullable — When using the query parameter `individualShippingEstimates=true`, it will contain the estimated shipping date (e.g. `2023-09-09T11:29:00+00:00`), otherwise it will contain `null`. - `useIndividualShippingEstimates` boolean — Shows the product's estimated shipping date in the `shippingEstimate` field from the `orderForm`. - `lockTTL` string, nullable — Estimate date of delivery. - `price` integer — Price in cents. - `listPrice` integer — List price in cents. - `tax` integer — Tax in cents. - `pickupStoreInfo` object — Information on the pickup store. - `isPickupStore` boolean — Indicates whether it is the pickup store. - `friendlyName` string, nullable — Friendly name. - `address` object, nullable — Address information. - `addressType` string — Type of address. For example, `Residential` or `Pickup`. - `postalCode` string — Postal code. - `city` string — City of the shipping address. - `state` string — State of the shipping address. - `country` string — Three letter ISO code of the country of the shipping address. - `street` string — Street of the shipping address. - `number` string — Number of the building, house or apartment in the shipping address. - `neighborhood` string — Neighborhood of the shipping address. - `complement` string, nullable — Complement to the shipping address, in case it applies. - `reference` string, nullable — Complement that might help locate the shipping address more precisely in case of delivery. - `geoCoordinates` number[] — Array with two strings that repesent geocoordinates: first latitude, then longitude. - `additionalInfo` string, nullable — Additional information. - `dockId` string, nullable — Corresponding dock ID. - `pickupPointId` string, nullable — Pickup point ID. - `pickupDistance` number — Pickup point distance. - `polygonName` string, nullable — Polygon name. - `transitTime` string — Transit time. For instance, "three business days" is represented as `3bd`. - `shipsTo` string[] — List of countries that the item may be shipped to. - `itemId` string — Unique ID of the item in the cart. This ID is generated by VTEX and is used to identify the item in the cart. - `deliveryChannels` object[] — List of available delivery channels. - `id` string — Delivery channel ID. - `selectedAddresses` object[] — Array with information on the selected addresses for the order. - `addressType` string — Type of address. For example, `Residential` or `Pickup`. - `receiverName` string, nullable — Name of the person who is going to receive the order. - `addressId` string, nullable — Address ID. - `isDisposable` boolean — Indicates whether the address is disposable. Addresses marked as `isDisposable = true` are not saved to the shopper's profile when the order is completed, while addresses with `isDisposable = false` definitely belong to the shopper. Behavior by address type: - `giftRegistry`, `pickup`, `search`, and `inStore`: always disposable, as they do not belong to the shopper navigating the cart. - `residential`: may be disposable. Addresses from a complete shopper profile, or entered by an authenticated shopper with a complete profile, are not disposable. All other residential addresses are disposable, including those from first-time purchases, since no complete profile exists yet. - `invoice`: does not have the `isDisposable` flag, since invoice addresses are of type `Address` rather than `ShippingAddress`. In practice, only authenticated shoppers can add invoice attachments to the cart, so they are never treated as disposable. - `commercial`: corresponds to company addresses used in B2B contexts and follows the same logic as residential addresses. When a residential address is marked as disposable and the profile is complete, authentication is required to complete the order. Additionally, when a disposable residential address is used to complete a purchase, saved cards cannot be used. - `postalCode` string — Postal code. - `city` string — City of the shipping address. - `state` string — State of the shipping address. - `country` string — Three letter ISO code of the country of the shipping address. - `street` string — Street of the shipping address. - `number` string — Number of the building, house or apartment in the shipping address. - `neighborhood` string — Neighborhood of the shipping address. - `complement` string, nullable — Complement to the shipping address, in case it applies. - `reference` string, nullable — Complement that might help locate the shipping address more precisely in case of delivery. - `geoCoordinates` number[] — Array with two strings that represent geocoordinates: first latitude, then longitude. - `availableAddresses` object[] — Array with information on the available addresses for the order. - `addressType` string — Type of address. For example, `Residential` or `Pickup`. - `receiverName` string, nullable — Name of the person who is going to receive the order. - `addressId` string, nullable — Address ID. - `isDisposable` boolean — Indicates whether the address is disposable. Addresses marked as `isDisposable = true` are not saved to the shopper's profile when the order is completed, while addresses with `isDisposable = false` are saved. Behavior by address type: - `giftRegistry`, `pickup`, `search`, and `inStore`: always disposable, as they do not belong to the shopper navigating the cart. - `residential`: may be disposable. Addresses from a complete shopper profile, or entered by an authenticated shopper with a complete profile, are not disposable. All other residential addresses are disposable, including those from first-time purchases, since no complete profile exists yet. - `invoice`: does not have the `isDisposable` flag, since invoice addresses are of type `Address` rather than `ShippingAddress`. In practice, only authenticated shoppers can add invoice attachments to the cart, so they are never treated as disposable. - `commercial`: corresponds to company addresses used in B2B contexts and follows the same logic as residential addresses. When a residential address is marked as disposable and the profile is complete, authentication is required to complete the order. Additionally, when a disposable residential address is used to complete a purchase, saved cards cannot be used. - `postalCode` string — Postal code. - `city` string — City of the shipping address. - `state` string — State of the shipping address. - `country` string — Three letter ISO code of the country of the shipping address. - `street` string — Street of the shipping address. - `number` string — Number of the building, house or apartment in the shipping address. - `neighborhood` string — Neighborhood of the shipping address. - `complement` string, nullable — Complement to the shipping address, in case it applies. - `reference` string, nullable — Complement that might help locate the shipping address more precisely in case of delivery. - `geoCoordinates` number[] — Array with two strings that represent geocoordinates: first latitude, then longitude. - `clientProfileData` object, nullable — Customer's profile information. - `email` string, nullable — Email address. - `firstName` string, nullable — First name. - `lastName` string — Last name. - `documentType` string — Type of the document informed by the customer. - `document` string — Document informed by the customer. - `phone` string — Phone number. - `corporateName` string, nullable — Company name, if the customer is a legal entity. - `tradeName` string, nullable — Trade name, if the customer is a legal entity. - `corporateDocument` string, nullable — Corporate document, if the customer is a legal entity. - `stateInscription` string, nullable — State inscription, if the customer is a legal entity. - `corporatePhone` string, nullable — Corporate phone number, if the customer is a legal entity. - `isCorporate` boolean — Indicates whether the customer is a legal entity. - `profileCompleteOnLoading` boolean — Indicates whether profile is complete on loading. - `profileErrorOnLoading` boolean, nullable — Indicates whether profile presents error on loading. - `customerClass` string, nullable — Customer class. - `paymentData` object — Information on the order's payment. - `giftCards` object[] — Gift card information, if it applies to the order. - `redemptionCode` string — Gift card redemption code. - `value` integer — Gift card value in cents. - `balance` integer — Gift card balance in cents. - `name` string — Gift card name. - `id` string — Gift card ID. - `inUse` boolean — Indicates whether gift card is in use. - `isSpecialCard` boolean — Indicates whether gift card is special. - `transactions` object[] — Information on each transaction pertinent to the order. - `isActive` boolean — Indicates whether transaction is active. - `transactionId` string — Transaction ID. - `merchantName` string — Merchant name. - `payments` object[] — Information on each payment. - `accountId` string — Account ID. - `bin` string, nullable — Bin. - `installments` integer — Number of installments. - `paymentSystem` string — Payment system. - `referenceValue` integer — Reference value for calculating interest rates, in case it applies. Displayed in cents. - `value` integer — Value including interest, in case it applies. Displayed in cents. - `sharedTransaction` boolean — Indicates whather transaction is shared. - `marketingData` object, nullable — Object containing promotion data such as coupon tracking information and internal or external UTMs. - `coupon` string — Sending an existing coupon code in this field will return the corresponding discount in the purchase. Use the [cart simulation](https://developers.vtex.com/vtex-rest-api/reference/orderform#orderformsimulation) request to check which coupons might apply before placing the order. - `utmSource` string — UTM source. - `utmMedium` string — UTM medium. - `utmCampaign` string — UTM campaign. - `utmiPage` string, nullable — utmi_page (internal utm). - `utmiPart` string, nullable — utmi_part (internal utm). - `utmiCampaign` string, nullable — utmi_campaign (internal utm). - `sellers` object[] — Information on each seller. - `id` string — Seller ID. - `name` string — Seller name. - `logo` string, nullable — Seller logo. - `minimumOrderValue` integer, nullable — Minimum order value configured at the seller, in cents. - `clientPreferencesData` object — Object containing preferences from the client who placed the order. - `locale` string — Client's locale. Examples: `pt-BR` and `en-US`. - `optinNewsLetter` boolean, nullable — `true` if the client opted to receive newsletter from the store. - `commercialConditionData` object, nullable — Object containing commercial condition information. - `storePreferencesData` object — Object containing data from the store's configuration (stored in VTEX's License Manager). - `giftRegistryData` object, nullable — Gift registry list information. - `openTextField` string, nullable — Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as `JSON` even if escaped. For that purpose, see [Creating customizable fields](https://developers.vtex.com/vtex-rest-api/docs/creating-customizable-fields-in-the-cart-with-checkout-api-1). - `invoiceData` object, nullable — Invoice data including billing address. - `address` object — Billing address. - `postalCode` string — Postal code. - `city` string — City name. - `state` string — State name. - `country` string — Country. - `street` string — Street name. - `number` string — Street number. - `neighborhood` string — Neighborhood. - `complement` string — Address complement. - `reference` string — Reference for location. - `geoCoordinates` number[] — Geographic coordinates (latitude, longitude). - `customData` object, nullable — Customer additional information. - `customApps` object[], nullable — Customizable apps created by the store. - `customFields` object[], nullable — Customizable fields created by the store. - `linkedEntity` object — Linked entity. - `type` 'order' | 'item' | 'address' — Linked entity type. - `id` string — Linked entity ID. - `fields` object[] — Custom fields. - `name` string — Custom field name. - `value` string — Custom field value. - `refId` string — Custom field reference ID. - `itemMetadata` object — Item metadata. - `items` object[] — List of objects containing metadata on each item in the order. - `id` string — Item ID. - `seller` string — Seller. - `name` string — Product name. - `skuName` string — SKU name. - `productId` string — Product ID. - `refId` string, nullable — Ref ID. - `ean` string, nullable — European Article Number. - `imageUrl` string — Image URL. - `detailUrl` string — Detail URL. - `hooksData` object, nullable — Hooks information. - `ratesAndBenefitsData` object — Information on rates and benefits that apply to the order. - `rateAndBenefitsIdentifiers` string[] — List with rates and benefits identifiers. - `teaser` string[] — List with rates and benefits teasers. - `subscriptionData` object, nullable — Subscription information. - `itemsOrdination` object, nullable — Object containing information about the ordering of items within the `orderForm`. - `criteria` string — Criteria adopted to order the items in the list. - `ascending` boolean — Indicates whether the ordering is ascending. --- [API](https://skmtc.net/vtex/apis/checkout-api.md) · [All operations](https://skmtc.net/vtex/apis/checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vtex/checkout-api/versions/fc777477b318/schema)