Choose a version:

App background

The app background target is for work that should happen while POS is open, but doesn't need a screen. Unlike render targets, it doesn't mount UI or update what merchants see in POS.

Anchor to Use casesUse cases

Transaction sync: Listen for completed sale, return, or exchange transactions and send data to your app backend.
Cash tracking workflows: Respond when cash tracking sessions start or complete.
Session-level state: Keep extension state updated while POS is open.

Anchor to App background targetApp background target

Anchor to POS app ready ,[object Object]POS app ready target

pos.app.ready.data

Runs once when POS is ready. Register event listeners in the entry function with shopify.addEventListener(). POS keeps the target active until the session ends.

Support

Components (0)

APIs (7)

Supported components

Available APIs

Examples

jsx

export default function extension() {

shopify.addEventListener('transactioncomplete', (transaction) => {

console.log('Transaction completed', transaction);

});

}

Examples

Description

jsx

export default function extension() {
  shopify.addEventListener('transactioncomplete', (transaction) => {
    console.log('Transaction completed', transaction);
  });
}

Description

Read the current cart state whenever POS updates it.

jsx

export default function extension() {
  shopify.cart.current.subscribe((cart) => {
    console.log('Cart changed', cart);
  });
}

Anchor to Event listener methodsEvent listener methods

The app background target adds these methods to the shopify global.

Anchor to addEventListener addEventListener <K extends keyof >(type: K, listener: (event: [K]) => void) => void required: Register a listener for a POS host event. Listeners are fire-and-forget: their return values are ignored, and their errors are caught without affecting the host or other listeners.
Anchor to removeEventListener removeEventListener <K extends keyof >(type: K, listener: (event: [K]) => void) => void required: Remove a listener previously registered with addEventListener. The listener reference must match the one used to register.

ShopifyEventMap

Maps Shopify POS event names to their corresponding payload types. Used as the generic type parameter for `shopify.addEventListener` and `shopify.removeEventListener`.

cashtrackingsessioncomplete
Dispatched when a cash tracking session closes after reconciliation.
```
CashTrackingSessionCompleteEvent
```
cashtrackingsessionstart
Dispatched when a cash tracking session opens.
```
CashTrackingSessionStartEvent
```
transactioncomplete
Dispatched when a sale, return, or exchange transaction completes. Narrow on `transactionType` to access per-type fields.
```
TransactionCompleteEvent
```

CashTrackingSessionCompleteEvent

Dispatched when a cash tracking session is successfully closed via reconciliation.

closingTime
ISO 8601 timestamp when the session was closed.
```
string
```
id
The numeric identifier for the cash tracking session.
```
number
```
openingTime
ISO 8601 timestamp when the session was opened.
```
string
```

CashTrackingSessionStartEvent

Dispatched when a cash tracking session is opened.

id
The numeric identifier for the cash tracking session.
```
number
```
openingTime
ISO 8601 timestamp when the session was opened.
```
string
```

TransactionCompleteEvent

Dispatched when a sale, return, or exchange transaction completes. Narrow on `transactionType` to access per-type fields.

SaleCompleteEvent | ReturnCompleteEvent | ExchangeCompleteEvent

SaleCompleteEvent

Dispatched when a sale transaction completes.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically zero for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
cashRoundingAdjustment
The cash rounding adjustment applied to this transaction as a `Money` object. Returns `undefined` when no cash rounding adjustment was applied.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Empty when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
draftCheckoutUuid
The UUID of the draft order's checkout. Set when the sale originated from a draft order; `undefined` otherwise.
```
string
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItems
An array of line items included in the sale transaction.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Empty for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Empty for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
tipAmount
The tip amount added to this transaction as a `Money` object. This represents the gratuity the customer chose to add on top of the grand total, typically for service-based businesses or hospitality transactions. Tipping can be enabled through POS settings and may be added as a percentage or fixed amount. Returns `undefined` when no tip was added or when tipping is not enabled for the transaction.
```
Money
```
transactionType
The transaction type identifier indicating which kind of transaction was completed (for example, `'Sale'` for new purchases, `'Return'` for refunds, `'Exchange'` for item swaps). Narrow on this field to access transaction-type-specific properties.
```
'Sale'
```

Money

Represents a monetary amount with currency information.

amount
The monetary amount as a number.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```

Customer

Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features.

id
The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems.
```
number
```

Discount

Represents a discount applied to a cart or transaction, including amount and description.

amount
The discount value to apply. For `'Percentage'` type, this represents the percentage value (For example, "10" for 10% off). For `'FixedAmount'` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```
discountDescription
A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns `undefined` when no description is provided.
```
string
```
type
The [discount type](https://help.shopify.com/en/manual/discounts/discount-types) applied to this line item. Can be either `'Percentage'` for percentage-based discounts or `'FixedAmount'` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed.
```
string
```

LineItem

Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry.

attributedUserId
The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics.
```
number
```
components
Bundle components for this line item. Only present for [product bundles](/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information.
```
LineItemComponent[]
```
discountAllocations
An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting.
```
DiscountAllocation[]
```
discounts
An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details.
```
Discount[]
```
hasSellingPlanGroups
Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options.
```
boolean
```
isGiftCard
Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows.
```
boolean
```
price
The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.
```
number
```
productId
The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details.
```
number
```
properties
The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data.
```
{ [key: string]: string; }
```
quantity
The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.
```
number
```
requiresSellingPlan
Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling.
```
boolean
```
sellingPlan
The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality.
```
SellingPlan
```
sku
The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification.
```
string
```
taxable
Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.
```
boolean
```
taxLines
An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.
```
TaxLine[]
```
title
The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.
```
string
```
uuid
The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.
```
string
```
variantId
The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details.
```
number
```
vendor
The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization.
```
string
```

LineItemComponent

Represents a component of a [product bundle](/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information.

discountAllocations
An array of discount allocations applied to this component, providing a detailed breakdown of how discounts are distributed across bundle components. Returns `undefined` if no allocations exist.
```
DiscountAllocation[]
```
price
The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing.
```
number
```
productId
The unique numeric identifier for the product this component represents, if applicable.
```
number
```
quantity
The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.
```
number
```
taxable
Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes.
```
boolean
```
taxLines
An array of tax lines applied to this component.
```
TaxLine[]
```
title
The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
```
string
```
variantId
The unique numeric identifier for the product variant this component represents, if applicable.
```
number
```

DiscountAllocation

Represents the allocation of a discount to a specific line item.

allocatedAmount
The amount of discount allocated.
```
MoneyV2
```

MoneyV2

Represents a monetary amount as a string with explicit currency code.

amount
The monetary amount as a string.
```
string
```
currencyCode
The ISO currency code (for example, USD, CAD).
```
string
```

TaxLine

Represents a tax line applied to an item or transaction.

enabled
Whether this tax is currently enabled.
```
boolean
```
price
The tax amount as a Money object.
```
Money
```
rate
The tax rate as a decimal number.
```
number
```
rateRange
The range of tax rates if applicable.
```
{ min: number; max: number; }
```
title
The title or name of the tax.
```
string
```
uuid
The unique identifier for this tax line.
```
string
```

SellingPlan

Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details.

deliveryInterval
The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).
```
string
```
deliveryIntervalCount
The number of intervals between deliveries.
```
number
```
digest
The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.
```
string
```
id
The unique identifier of the selling plan.
```
number
```
name
The name of the POS device.
```
string
```

Payment

Represents a payment applied to a transaction, including the amount, currency, and payment method type.

amount
The payment amount.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```
type
The payment method type.
```
PaymentMethod
```

PaymentMethod

The available payment method types for POS transactions.

'Cash' | 'Custom' | 'CreditCard' | 'CardPresentRefund' | 'StripeCardPresentRefund' | 'GiftCard' | 'StripeCreditCard' | 'ShopPay' | 'StoreCredit' | 'Unknown'

ShippingLine

Represents a shipping charge applied to an order, including the price and applicable taxes.

handle
The handle identifier for the shipping method.
```
string
```
price
The price of the shipping as a Money object.
```
Money
```
taxLines
An array of individual tax lines showing tax breakdown.
```
TaxLine[]
```
title
The display title of the shipping method.
```
string
```

ReturnCompleteEvent

Dispatched when a return transaction completes.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically zero for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
cashRoundingAdjustment
The cash rounding adjustment applied to this transaction as a `Money` object. Returns `undefined` when no cash rounding adjustment was applied.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Empty when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
exchangeId
The exchange ID when this return is the gift-card side of an exchange; `undefined` for standalone returns.
```
number
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItems
An array of line items included in the return transaction.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
refundId
The refund ID. `undefined` when the return did not issue a refund (for example, store-credit-only returns).
```
number
```
returnId
The return ID for the completed return transaction.
```
number
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Empty for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Empty for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
tipAmount
The tip amount added to this transaction as a `Money` object. This represents the gratuity the customer chose to add on top of the grand total, typically for service-based businesses or hospitality transactions. Tipping can be enabled through POS settings and may be added as a percentage or fixed amount. Returns `undefined` when no tip was added or when tipping is not enabled for the transaction.
```
Money
```
transactionType
The transaction type identifier indicating which kind of transaction was completed (for example, `'Sale'` for new purchases, `'Return'` for refunds, `'Exchange'` for item swaps). Narrow on this field to access transaction-type-specific properties.
```
'Return'
```

ExchangeCompleteEvent

Dispatched when an exchange transaction completes.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically zero for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
cashRoundingAdjustment
The cash rounding adjustment applied to this transaction as a `Money` object. Returns `undefined` when no cash rounding adjustment was applied.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Empty when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
exchangeId
The exchange ID linking the return and sale sides of the exchange.
```
number
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItemsAdded
An array of line items added to the customer in the exchange.
```
LineItem[]
```
lineItemsRemoved
An array of line items removed from the customer in the exchange.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
returnId
The return-side ID. `undefined` when the exchange has no return side.
```
number
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Empty for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Empty for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
tipAmount
The tip amount added to this transaction as a `Money` object. This represents the gratuity the customer chose to add on top of the grand total, typically for service-based businesses or hospitality transactions. Tipping can be enabled through POS settings and may be added as a percentage or fixed amount. Returns `undefined` when no tip was added or when tipping is not enabled for the transaction.
```
Money
```
transactionType
The transaction type identifier indicating which kind of transaction was completed (for example, `'Sale'` for new purchases, `'Return'` for refunds, `'Exchange'` for item swaps). Narrow on this field to access transaction-type-specific properties.
```
'Exchange'
```

Anchor to Best practicesBest practices

Use it for session-level work: Choose this target for logic that should run while POS is open and doesn't need a visible surface.
Use render targets for UI: If merchants need to see, confirm, or act on information, use a render target instead.
Initialize predictably: The app background target starts with each POS session, so setup code should be safe to run more than once.
Store only what you need: Keep local storage writes small and limited to data you need across POS sessions.

Anchor to LimitationsLimitations

App background extensions are currently observation-only and can't mutate POS state with the available APIs.

Was this page helpful?