SwapService

internal.internal.SwapService

Handles swaps

Properties

__configModule__Record<string, unknown>

__container__anyRequired

__moduleDeclaration__Record<string, unknown>

cartService_CartServiceRequired

customShippingOptionService_CustomShippingOptionServiceRequired

eventBus_EventBusServiceRequired

fulfillmentService_FulfillmentServiceRequired

lineItemAdjustmentService_LineItemAdjustmentServiceRequired

lineItemService_LineItemServiceRequired

manager_EntityManagerRequired

orderService_OrderServiceRequired

paymentProviderService_PaymentProviderServiceRequired

productVariantInventoryService_ProductVariantInventoryServiceRequired

returnService_ReturnServiceRequired

shippingOptionService_ShippingOptionServiceRequired

swapRepository_Repository<Swap>Required

totalsService_TotalsServiceRequired

transactionManager_undefined | EntityManagerRequired

EventsobjectRequired

Events.CREATEDstringRequired

Events.FULFILLMENT_CREATEDstringRequired

Events.PAYMENT_CAPTUREDstringRequired

Events.PAYMENT_CAPTURE_FAILEDstringRequired

Events.PAYMENT_COMPLETEDstringRequired

Events.PROCESS_REFUND_FAILEDstringRequired

Events.RECEIVEDstringRequired

Events.REFUND_PROCESSEDstringRequired

Events.SHIPMENT_CREATEDstringRequired

Accessors

activeManager_

Protected get activeManager_(): EntityManager

Returns

EntityManager

EntityManagerEntityManagerRequired

Inherited from

TransactionBaseService.activeManager_

Methods

areReturnItemsValid

Protected areReturnItemsValid(returnItems): Promise<boolean>

Parameters

returnItemsWithRequiredProperty<Partial<ReturnItem>, "item_id">[]Required

Returns

Promise<boolean>

PromisePromise<boolean>Required

---

atomicPhase_

Protected atomicPhase_<TResult, TError>(work, isolationOrErrorHandler?, maybeErrorHandlerOrDontFail?): Promise<TResult>

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

TResultobjectRequired

TErrorobjectRequired

Parameters

work(transactionManager: EntityManager) => Promise<TResult>Required

the transactional work to be done

isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>

the isolation level to be used for the work.

maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>

Potential error handler

Returns

Promise<TResult>

PromisePromise<TResult>Required

the result of the transactional work

Inherited from

TransactionBaseService.atomicPhase_

---

cancel

cancel(swapId): Promise<Swap>

Cancels a given swap if possible. A swap can only be canceled if all related returns, fulfillments, and payments have been canceled. If a swap is associated with a refund, it cannot be canceled.

Parameters

swapIdstringRequired

the id of the swap to cancel.

Returns

Promise<Swap>

PromisePromise<Swap>Required

the canceled swap.

---

cancelFulfillment

cancelFulfillment(fulfillmentId): Promise<Swap>

Cancels a fulfillment (if related to a swap)

Parameters

fulfillmentIdstringRequired

the ID of the fulfillment to cancel

Returns

Promise<Swap>

PromisePromise<Swap>Required

updated swap

---

create

create(order, returnItems, additionalItems?, returnShipping?, custom?): Promise<Swap>

Creates a swap from an order, with given return items, additional items and an optional return shipping method.

Parameters

orderOrderRequired

the order to base the swap off

returnItemsWithRequiredProperty<Partial<ReturnItem>, "item_id">[]Required

the items to return in the swap

additionalItemsPick<LineItem, "variant_id" | "quantity">[]

the items to send to the customer

returnShippingobject

an optional shipping method for returning the returnItems

returnShipping.option_idstringRequired

returnShipping.pricenumber

customobject

contains relevant custom information. This object may include no_notification which will disable sending notification when creating swap. If set, it overrules the attribute inherited from the order

custom.allow_backorderboolean

custom.idempotency_keystring

custom.location_idstring

custom.no_notificationboolean

Returns

Promise<Swap>

PromisePromise<Swap>Required

the newly created swap

---

createCart

createCart(swapId, customShippingOptions?, context?): Promise<Swap>

Creates a cart from the given swap. The cart can be used to pay for differences associated with the swap. The swap represented by the swapId must belong to the order. Fails if there is already a cart on the swap.

Parameters

swapIdstringRequired

the id of the swap to create the cart from

customShippingOptions{ option_id: string ; price: number }[]

the shipping options

contextobject

context.sales_channel_idstring

Returns

Promise<Swap>

PromisePromise<Swap>Required

the swap with its cart_id prop set to the id of the new cart.

---

createFulfillment

createFulfillment(swapId, config?): Promise<Swap>

Fulfills the additional items associated with the swap. Will call the fulfillment providers associated with the shipping methods.

Parameters

swapIdstringRequired

the id of the swap to fulfill,

configCreateShipmentConfig

optional configurations, includes optional metadata to attach to the shipment, and a no_notification flag.

Returns

Promise<Swap>

PromisePromise<Swap>Required

the updated swap with new status and fulfillments.

---

createShipment

createShipment(swapId, fulfillmentId, trackingLinks?, config?): Promise<Swap>

Marks a fulfillment as shipped and attaches tracking numbers.

Parameters

swapIdstringRequired

the id of the swap that has been shipped.

fulfillmentIdstringRequired

the id of the specific fulfillment that has been shipped

trackingLinks{ tracking_number: string }[]

the tracking numbers associated with the shipment

configCreateShipmentConfig

optional configurations, includes optional metadata to attach to the shipment, and a noNotification flag.

Returns

Promise<Swap>

PromisePromise<Swap>Required

the updated swap with new fulfillments and status.

---

deleteMetadata

deleteMetadata(swapId, key): Promise<Swap>

Dedicated method to delete metadata for a swap.

Parameters

swapIdstringRequired

the order to delete metadata from.

keystringRequired

key for metadata field

Returns

Promise<Swap>

PromisePromise<Swap>Required

resolves to the updated result.

---

list

list(selector, config?): Promise<Swap[]>

List swaps.

Parameters

selectorSelector<Swap>Required

the query object for find

configFindConfig<Swap>

the configuration used to find the objects. contains relations, skip, and take.

Returns

Promise<Swap[]>

PromisePromise<Swap[]>Required

the result of the find operation

---

listAndCount

listAndCount(selector, config?): Promise<[Swap[], number]>

List swaps.

Parameters

selectorSelector<Swap>Required

the query object for find

configFindConfig<Swap>

the configuration used to find the objects. contains relations, skip, and take.

Returns

Promise<[Swap[], number]>

PromisePromise<[Swap[], number]>Required

the result of the find operation

---

processDifference

processDifference(swapId): Promise<Swap>

Process difference for the requested swap.

Parameters

swapIdstringRequired

id of a swap being processed

Returns

Promise<Swap>

PromisePromise<Swap>Required

processed swap

---

registerCartCompletion

registerCartCompletion(swapId): Promise<Swap>

Register a cart completion

Parameters

swapIdstringRequired

The id of the swap

Returns

Promise<Swap>

PromisePromise<Swap>Required

swap related to the cart

---

registerReceived

registerReceived(id): Promise<Swap>

Registers the swap return items as received so that they cannot be used as a part of other swaps/returns.

Parameters

idanyRequired

the id of the order with the swap.

Returns

Promise<Swap>

PromisePromise<Swap>Required

the resulting order

---

retrieve

retrieve(swapId, config?): Promise<Swap>

Retrieves a swap with the given id.

Parameters

swapIdstringRequired

the id of the swap to retrieve

configOmit<FindConfig<Swap>, "select"> & { select?: string[] }

the configuration to retrieve the swap

Returns

Promise<Swap>

PromisePromise<Swap>Required

the swap

---

retrieveByCartId

retrieveByCartId(cartId, relations?): Promise<Swap>

Retrieves a swap based on its associated cart id

Parameters

cartIdstringRequired

the cart id that the swap's cart has

relationsstring[]

the relations to retrieve swap

Returns

Promise<Swap>

PromisePromise<Swap>Required

the swap

---

shouldRetryTransaction_

Protected shouldRetryTransaction_(err): boolean

Parameters

errRecord<string, unknown> | { code: string }Required

Returns

boolean

booleanboolean

Inherited from

TransactionBaseService.shouldRetryTransaction_

---

transformQueryForCart

Protected transformQueryForCart(config): Omit<FindConfig<Swap>, "select"> & { select?: string[] } & { cartRelations: undefined | string[] ; cartSelects: undefined | keyof Cart[] }

Transform find config object for retrieval.

Parameters

configOmit<FindConfig<Swap>, "select"> & { select?: string[] }Required

parsed swap find config

Returns

Omit<FindConfig<Swap>, "select"> & { select?: string[] } & { cartRelations: undefined | string[] ; cartSelects: undefined | keyof Cart[] }

[`Omit`](/references/js-client/admin_auth/modules/admin_auth.internal#omit)<[`FindConfig`](/references/js-client/internal/interfaces/admin_discounts.internal.internal.FindConfig)<[`Swap`](/references/js-client/internal/classes/admin_collections.internal.Swap)\>, ``"select"``\> & { `select?`: `string`[] } & { `cartRelations`: `undefined` \| `string`[] ; `cartSelects`: `undefined` \| keyof [`Cart`](/references/js-client/internal/classes/admin_collections.internal.Cart)[] }Omit<FindConfig<Swap>, "select"> & { select?: string[] } & { cartRelations: undefined | string[] ; cartSelects: undefined | keyof Cart[] }

transformed find swap config

---

update

update(swapId, update): Promise<Swap>

Update the swap record.

Parameters

swapIdstringRequired

id of a swap to update

updatePartial<Swap>Required

new data

Returns

Promise<Swap>

PromisePromise<Swap>Required

updated swap record

---

withTransaction

withTransaction(transactionManager?): SwapService

Parameters

transactionManagerEntityManager

Returns

SwapService

SwapServiceSwapServiceRequired

Inherited from

TransactionBaseService.withTransaction