---
title: "Create and finalize shopping carts"
method: POST
path: "/v3/checkout/shoppingCarts/finalize"
tags: ["ShoppingCart"]
---

# Create and finalize shopping carts

`POST /v3/checkout/shoppingCarts/finalize`

## Request

- Base URL: `https://marketplace.appdirect.com/api`
- URL: `https://marketplace.appdirect.com/api/v3/checkout/shoppingCarts/finalize`
- Auth: none declared. Required headers: `AD-ShoppingCart-Partner`
- TypeScript: <https://skmtc.dev/appdirect/apis/companies/docs/v3/checkout/shoppingCarts/finalize/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates and finalizes a shopping cart in a single request

## Headers

- `AD-ShoppingCart-Partner` string, required
- `AD-Timezone` string

## Request body

- ShoppingCart: Information about the accredited agents associated with shopping carts
  - `id` string: Shopping cart ID
  - `createdOn` string: Shopping cart creation date
  - `ownerUserId` string: Cart owner user ID
  - `ownerCompanyId` string: Cart owner company ID
  - `buyerType` 'CUSTOMER' | 'PLATFORM_OWNER' | 'PARTNER': Describes the buyer's relationship with the platform, either CUSTOMER (end user), PLATFORM_OWNER (sales representative) or PARTNER (reseller)
  - `currency` 'USD' | 'CAD' | 'EUR' | 'JPY' | 'GBP' | 'KRW' | 'CHF' | 'SEK' | 'SGD' | 'MYR' | 'AUD' | 'MXN' | 'INR' | 'BRL' | 'DKK' | 'NZD' | 'NOK' | 'ZAR' | 'PHP' | 'CNY' | 'SAR' | 'GTQ' | 'IDR' | 'ARS' | 'COP' | 'PEN': Supported currencies for the system
  - `status` string: Shopping cart status
  - `isBlocked` boolean: Shopping Cart is locked waiting for an external event
  - `paymentMethodId` string: Payment method ID
  - `preAuthId` string: Cart payment pre-authorization ID
  - `locale` string: Locale of shopping cart (ISO 639 language, ISO 3166 country, variant).
  - `buyerUserId` string: User ID of the buyer (customer, reseller, sales representative) who initiates the purchase
  - `buyerCompanyId` string: Buyer company ID
  - `items` ShoppingCartItem[]
    - `id` string: Item UUID
    - `referenceId` string: A 'local' ID for the item, which can be used in requests instead of the full UUID. Use the ref:{referenceId} format.
    - `subscriptionId` string: Existing subscription UUID.
    - `pricingPlanId` string: ID of the pricing plan that the user is going to purchase
    - `serviceConfiguration` ServiceConfiguration: Service Configuration
      - `date` string, date: Custom date (YYYY-MM-DD) that determines when the purchased service is activated
      - `strategy` 'CUSTOM' | 'IMMEDIATELY': Service strategy. By default, the service is activated immediately. To set a custom activation date, specify CUSTOM.
    - `billingConfiguration` BillingConfiguration: Determines when the billing cycle starts. Set UPON_SERVICE_ACTIVATION to start the billing cycle according to the specified provisioning strategy (either immediately after the opportunity is finalized or on a custom provisioning date). Set NEXT_BILLING_CYCLE to start the billing cycle according to the marketplace billing configuration (for example, first of the month). Set CUSTOM to start the billing cycle on a specified date in the future.
      - `date` number: Custom billing activation date in UNIX Epoch milliseconds. This date is required when the billing strategy is CUSTOM. Do not set the date when the strategy is UPON_SERVICE_ACTIVATION or NEXT_BILLING_CYCLE.
      - `strategy` 'CUSTOM' | 'NEXT_BILLING_CYCLE' | 'UPON_SERVICE_ACTIVATION'
    - `discountCode` string: Discount applied to the product
    - `discountId` string: Discount ID
    - `customPrices` CustomPrice[]: Definition of custom prices for the purchase
      - `costId` string, required: ID of the cost/pricing item for which to override prices.
      - `priceType` 'RESELLER_PURCHASE_PRICE' | 'MARKETPLACE_RESELLER_PURCHASE_PRICE'
      - `pricingStrategy` 'FREE' | 'FLAT' | 'UNIT' | 'TIERED' | 'VOLUME' | 'VARIABLE_PRICE_STRATEGIES' | 'UNLIMITED' | 'CUSTOM': Pricing strategy
      - `definition` Definition: Definition for flat/unit range prices.
        - `price` number: Flat price.
        - `priceRanges` PriceRange[]: Unit range prices.
          - `min` number, required
          - `max` number
          - `price` number, required
          - `salePrice` string, amount: Regular sale price
          - `wholesalePrice` string, amount: Wholesale sale price
    - `units` Unit[]: List of units included in the product
      - `quantity` number: Quantity
      - `unit` string: Unit
    - `customAttributes` ItemCustomAttributes: Collection of custom attributes
      - `vendorRequiredFields` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
      - `subscription` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
    - `customContractConfiguration` CustomContractConfiguration: Configuration to use for custom contract
      - `minimumServiceLength` integer, required: Minimum pricing duration of the pricing plan
      - `minimumServiceLengthUnit` 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'SIX_MONTHS' | 'YEARLY' | 'TWO_YEARS' | 'THREE_YEARS', required: Time unit for contract length. This property must have the same value as the contract length unit configured for the pricing plan.
      - `endOfContractGracePeriod` integer: Grace period after the end of the contract
      - `endOfContractGracePeriodUnit` 'NONE' | 'INFINITY' | 'DAY' | 'MONTH': End-of-contract grace period unit. Time unit by which the endOfContractGracePeriod is measured.
      - `contractCancellationPeriodLimit` integer: Contract cancellation period limit
      - `contractCancellationPeriodUnit` 'NONE' | 'DAY': Cancellation period unit. Time unit by which the contractCancellationPeriodLimit is measured.
      - `continueWithoutContract` boolean: Determines whether to continue the subscription without a contract
      - `autoExtensionPricingId` string: The edition pricing ID to which to bind the contract when it is automatically renewed. To retrieve the value, use the "uuid" value from the "Read payment plan" https://help.appdirect.com/api/appdirect.html#read-payment-plan request.
      - `terminationFeeGracePeriod` integer: The termination fee grace period
      - `terminationFeeGracePeriodUnit` 'NONE' | 'INFINITY' | 'DAY' | 'MONTH': End-of-contract grace period unit. Time unit by which the endOfContractGracePeriod is measured.
      - `blockContractUpgrades` boolean: Determines whether to block upgrades to the contract terms
      - `blockContractDowngrades` boolean: Determines whether to block downgrades to the contract terms
      - `blockSwitchToShorterContract` boolean: Determines whether to block the ability to switch to a shorter contract
      - `keepContractDateOnPlanChange` boolean: Determines whether to keep the contract date if the plan changes
      - `alignWithParentCycleStartDate` boolean: For add-on products, determines whether to align the contract start date with the parent subscription start date. This is an internal setting.
      - `unitTerms` object: List of contract unit terms
      - `sourceId` string: The UUID of the custom contract creator
      - `terminationFee` TerminationFee: Termination Fee object
        - `feeType` 'FIXED' | 'PERCENTAGE'
        - `amount` number
        - `description` string
      - `contractFee` number: Contract Fee
  - `customAttributes` object: Collection of custom attributes linked to cart entities
    - `purchase` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
    - `buyerUser` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
    - `buyerCompany` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
    - `ownerUser` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
    - `ownerCompany` CustomAttributes: Specify custom attributes as key-value pairs for the purchase. Values can be strings (for text) or string arrays (for checkboxes). Marketplace managers must create the custom attributes in the user interface before they can be used in API calls.
  - `associations` Association[]: Item associations
    - `parentItemId` string: Parent product UUID or $item[referenceId] to reference the item in the cart.
    - `childItemIds` string[]: Child products UUID or $item[referenceId] to reference the item in the cart.
    - `type` 'ADDON'
  - `fees` Fee[]: Cart fees
    - `id` string: Fee ID
    - `externalId` string: External ID assigned by the fee provider service
    - `createdOn` string: Fee creation date and time
    - `key` string: Key used to identify fee type
    - `currency` string: Currency code (ISO 4217) of the fee
    - `amount` number: Fee amount
    - `description` Description: Description of the fee
      - `defaultDescription` string: Description of the fee
      - `localizedDescriptions` object: Localized description texts. The default is determined by the marketplace's default locale setting.
      - `params` object: Dynamic parameters to populate within descriptions. Reserved for values whose formats need to be localized, such as dates.
    - `revenueShare` RevenueShare: Revenue shares of the fee sent to AppDirect, the marketplace owner, and the product vendor. The total of all three revenue shares must be 1.00.
      - `appdirect` number: Revenue share sent to AppDirect, as a fraction of 1.00
      - `channel` number: Revenue share sent to the marketplace owner, as a fraction of 1.00
      - `vendor` number: Revenue share sent to the product vendor, as a fraction of 1.00
    - `itemIds` string[]: List of item IDs
    - `metadata` object: Metadata
  - `accreditedAgents` AccreditedAgent[]
    - `userId` string: Accredited agent to whom the purchase is attributed.
    - `companyId` string: Company of the accredited agent to whom the purchase is attributed.

## Response `202`

ACCEPTED

- ShoppingCartRequestAcceptedResponse (unresolved $ref)

## Other responses

- `401`: NOT AUTHORIZED

## Changes

- **2026-11-06** `1fc240f06971`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/appdirect/apis/companies/changes/v3/checkout/shoppingCarts/finalize/post.md)

---

[API](https://skmtc.dev/appdirect/apis/companies.md) - [All operations](https://skmtc.dev/appdirect/apis/companies/llms.txt) - [OpenAPI document](https://skmtc.dev/appdirect/apis/companies/revisions/1fc240f06971?raw)