asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
fd317f1a6ba0952999e2de5c4e649376e6afab21
medusa-store/www/apps/docs/content/references/fulfillment/classes/AbstractFulfillmentService.mdx
Shahed Nasser f802e2460f docs: TSDoc + reference of fulfillment service (#5761)
2023-11-29 11:58:08 +00:00

2940 lines
86 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
displayed_sidebar: modules
slug: /modules/carts-and-checkout/backend/add-fulfillment-provider
---
import ParameterTypes from "@site/src/components/ParameterTypes"
# How to Create a Fulfillment Provider
In this document, you’ll learn how to create a fulfillment provider to a Medusa backend and the methods you must implement in it. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](https://docs.medusajs.com/modules/carts-and-checkout/shipping).
## Overview
A fulfillment provider is the shipping provider used to fulfill orders and deliver them to customers. An example of a fulfillment provider is FedEx.
By default, a Medusa Backend has a `manual` fulfillment provider which has minimal implementation. It allows you to accept orders and fulfill them manually. However, you can integrate any fulfillment provider into Medusa, and your fulfillment provider can interact with third-party shipping providers.
A fulfillment provider is a service that extends the `AbstractFulfillmentService` and implements its methods. So, adding a fulfillment provider is as simple as creating a service file in `src/services`.
The file's name is the fulfillment provider's class name as a slug and without the word `Service`. For example, if you're creating a `MyFulfillmentService` class, the file name is `src/services/my-fulfillment.ts`.
```ts title=src/services/my-fulfillment.ts
import { AbstractFulfillmentService } from "@medusajs/medusa"
class MyFulfillmentService extends AbstractFulfillmentService {
// methods here...
}
```
---
## Identifier Property
The `FulfillmentProvider` entity has 2 properties: `identifier` and `is_installed`. The `identifier` property in the class is used when the fulfillment provider is created in the database.
The value of this property is also used to reference the fulfillment provider throughout Medusa. For example, it is used to [add a fulfillment provider](https://docs.medusajs.com/api/admin#regions\_postregionsregionfulfillmentproviders) to a region.
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
static identifier = "my-fulfillment"
// ...
}
```
---
## constructor
You can use the `constructor` of your fulfillment provider to access the different services in Medusa through dependency injection.
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
Additionally, if you’re creating your fulfillment provider as an external plugin to be installed on any Medusa backend and you want to access the options added for the plugin, you can access it in the constructor.
### Example
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
static identifier = "my-fulfillment"
// ...
}
```
### Parameters
<ParameterTypes parameters={[
{
"name": "container",
"type": "[MedusaContainer](../types/MedusaContainer.mdx)",
"description": "An instance of `MedusaContainer` that allows you to access other resources, such as services, in your Medusa backend.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "createScope",
"type": "() => [MedusaContainer](../types/MedusaContainer.mdx)",
"description": "",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "registerAdd",
"type": "`<T>`(`name`: `string`, `registration`: `T`) => [MedusaContainer](../types/MedusaContainer.mdx)",
"description": "",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
},
{
"name": "config",
"type": "`Record<string, unknown>`",
"description": "If this fulfillment provider is created in a plugin, the plugin's options are passed in this parameter.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
___
## Methods
### calculatePrice
This method is used in different places, including:
1. When the shipping options for a cart are retrieved during checkout. If a shipping option has their `price_type` set to calculated, this method is used to set the amount of the returned shipping option.
2. When a shipping method is created. If the shipping option associated with the method has their `price_type` set to `calculated`, this method is used to set the `price` attribute of the shipping method in the database.
3. When the cart's totals are calculated.
#### Example
An example of calculating the price based on some custom logic:
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async calculatePrice(
optionData: Record<string, unknown>,
data: Record<string, unknown>,
cart: Cart
): Promise<number> {
return cart.items.length * 1000
}
}
```
If your fulfillment provider does not provide any dynamically calculated rates you can return any static value or throw an error. For example:
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async calculatePrice(
optionData: Record<string, unknown>,
data: Record<string, unknown>,
cart: Cart
): Promise<number> {
throw new Error("Method not implemented.")
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "optionData",
"type": "[ShippingOptionData](../types/ShippingOptionData.mdx)",
"description": "The `data` object of the selected shipping option.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "data",
"type": "[FulfillmentProviderData](../types/FulfillmentProviderData.mdx)",
"description": "A `data` object that is different based on the context it's used in:\n\n1. If the price is being calculated for the list of shipping options available for a cart, it's the `data` object of the shipping option.\n2. If the price is being calculated when the shipping method is being created, it's the data returned by the [validateFulfillmentData](../interfaces/FulfillmentService.mdx#validatefulfillmentdata) method used during the shipping method creation.\n3. If the price is being calculated while calculating the cart's totals, it will be the data object of the cart's shipping method.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "cart",
"type": "[Cart](Cart.mdx)",
"description": "A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "billing_address",
"type": "[Address](Address.mdx)",
"description": "The details of the billing address associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "billing_address_id",
"type": "`string`",
"description": "The billing address's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "completed_at",
"type": "`Date`",
"description": "The date with timezone at which the cart was completed.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "context",
"type": "`Record<string, unknown>`",
"description": "The context of the cart which can include info like IP or user agent.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "customer",
"type": "[Customer](Customer.mdx)",
"description": "The details of the customer the cart belongs to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "customer_id",
"type": "`string`",
"description": "The customer's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "deleted_at",
"type": "`null` \\| `Date`",
"description": "The date with timezone at which the resource was deleted.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discount_total",
"type": "`number`",
"description": "The total of discount rounded",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discounts",
"type": "[Discount](Discount.mdx)[]",
"description": "An array of details of all discounts applied to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "email",
"type": "`string`",
"description": "The email associated with the cart",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_tax_total",
"type": "`number`",
"description": "The total of gift cards with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_total",
"type": "`number`",
"description": "The total of gift cards",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_cards",
"type": "[GiftCard](GiftCard.mdx)[]",
"description": "An array of details of all gift cards applied to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The cart's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "idempotency_key",
"type": "`string`",
"description": "Randomly generated key used to continue the completion of a cart in case of failure.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "item_tax_total",
"type": "`null` \\| `number`",
"description": "The total of items with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[LineItem](LineItem.mdx)[]",
"description": "The line items added to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "metadata",
"type": "`Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "object",
"type": "`\"cart\"`",
"description": "",
"optional": false,
"defaultValue": "\"cart\"",
"expandable": false,
"children": []
},
{
"name": "payment",
"type": "[Payment](Payment.mdx)",
"description": "The details of the payment associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "payment_authorized_at",
"type": "`Date`",
"description": "The date with timezone at which the payment was authorized.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "payment_id",
"type": "`string`",
"description": "The payment's ID if available",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "payment_session",
"type": "`null` \\| [PaymentSession](PaymentSession.mdx)",
"description": "The details of the selected payment session in the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "payment_sessions",
"type": "[PaymentSession](PaymentSession.mdx)[]",
"description": "The details of all payment sessions created on the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "raw_discount_total",
"type": "`number`",
"description": "The total of discount",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refundable_amount",
"type": "`number`",
"description": "The amount that can be refunded",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refunded_total",
"type": "`number`",
"description": "The total amount refunded if the order associated with this cart is returned.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "region",
"type": "[Region](Region.mdx)",
"description": "The details of the region associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "region_id",
"type": "`string`",
"description": "The region's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "sales_channel",
"type": "[SalesChannel](SalesChannel.mdx)",
"description": "The details of the sales channel associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "sales_channel_id",
"type": "`null` \\| `string`",
"description": "The sales channel ID the cart is associated with.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_address",
"type": "`null` \\| [Address](Address.mdx)",
"description": "The details of the shipping address associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_address_id",
"type": "`string`",
"description": "The shipping address's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_methods",
"type": "[ShippingMethod](ShippingMethod.mdx)[]",
"description": "The details of the shipping methods added to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_tax_total",
"type": "`null` \\| `number`",
"description": "The total of shipping with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_total",
"type": "`number`",
"description": "The total of shipping",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "subtotal",
"type": "`number`",
"description": "The subtotal of the cart",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "tax_total",
"type": "`null` \\| `number`",
"description": "The total of tax",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "total",
"type": "`number`",
"description": "The total amount of the cart",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "type",
"type": "[CartType](../enums/CartType.mdx)",
"description": "The cart's type.",
"optional": false,
"defaultValue": "default",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;number&#62;",
"optional": false,
"defaultValue": "",
"description": "Used to set the price of the shipping method or option, based on the context the method is used in.",
"expandable": false,
"children": [
{
"name": "number",
"type": "`number`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### canCalculate
This method is used to determine whether a shipping option is calculated dynamically or flat rate. It is called if the `price_type` of the shipping option being created is set to calculated.
#### Example
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async canCalculate(
data: Record<string, unknown>
): Promise<boolean> {
return data.id === "my-fulfillment-dynamic"
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "[ShippingOptionData](../types/ShippingOptionData.mdx)",
"description": "The `data` object of the shipping option being created. You can use this data to determine whether the shipping option should be calculated or not.\nThis is useful if the fulfillment provider you are integrating has both flat rate and dynamically priced fulfillment options.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;boolean&#62;",
"optional": false,
"defaultValue": "",
"description": "If this method returns `true`, that means that the price can be calculated dynamically and the shipping option can have the `price_type` set to calculated.\nThe amount property of the shipping option will then be set to null. The amount will be created later when the shipping method is created on checkout using the [calculatePrice](../interfaces/FulfillmentService.mdx#calculateprice) method.\nIf the method returns `false`, an error is thrown as it means the selected shipping option is invalid and it can only have the `flat_rate` price type.",
"expandable": false,
"children": [
{
"name": "boolean",
"type": "`boolean`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### cancelFulfillment
This method is called when a fulfillment is cancelled by the admin. This fulfillment can be for an order, a claim, or a swap.
#### Example
This is the basic implementation of the method for a fulfillment provider that doesn't interact with a third-party provider to cancel the fulfillment:
```ts
class MyFulfillmentService extends FulfillmentService {
// ...
async cancelFulfillment(
fulfillment: Record<string, unknown>
): Promise<any> {
return {}
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "fulfillment",
"type": "[FulfillmentProviderData](../types/FulfillmentProviderData.mdx)",
"description": "The `data` attribute of the fulfillment being canceled",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any&#62;",
"optional": false,
"defaultValue": "",
"description": "The method isn't expected to return any specific data.",
"expandable": false,
"children": [
{
"name": "any",
"type": "`any`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### createFulfillment
This method is used when a fulfillment is created for an order, a claim, or a swap.
#### Example
Here is a basic implementation of `createFulfillment` for a fulfillment provider that does not interact with any third-party provider to create the fulfillment:
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async createFulfillment(
data: Record<string, unknown>,
items: LineItem,
order: Order,
fulfillment: Fulfillment
) {
// No data is being sent anywhere
// No data to be stored in the fulfillment's data object
return {}
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "[ShippingMethodData](../types/ShippingMethodData.mdx)",
"description": "The `data` object of the shipping method associated with the resource, such as the order.\nYou can use it to access the data specific to the shipping option. This is based on your implementation of previous methods.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[LineItem](LineItem.mdx)[]",
"description": "The line items in the order to be fulfilled. The admin can choose all or some of the items to fulfill.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "adjustments",
"type": "[LineItemAdjustment](LineItemAdjustment.mdx)[]",
"description": "The details of the item's adjustments, which are available when a discount is applied on the item.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "allow_discounts",
"type": "`boolean`",
"description": "Flag to indicate if the Line Item should be included when doing discount calculations.",
"optional": false,
"defaultValue": "true",
"expandable": false,
"children": []
},
{
"name": "cart",
"type": "[Cart](Cart.mdx)",
"description": "The details of the cart that the line item may belongs to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "cart_id",
"type": "`string`",
"description": "The ID of the cart that the line item may belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "claim_order",
"type": "[ClaimOrder](ClaimOrder.mdx)",
"description": "The details of the claim that the line item may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "claim_order_id",
"type": "`string`",
"description": "The ID of the claim that the line item may belong to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "description",
"type": "`null` \\| `string`",
"description": "A more detailed description of the contents of the Line Item.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discount_total",
"type": "`null` \\| `number`",
"description": "The total of discount of the line item rounded",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "fulfilled_quantity",
"type": "`null` \\| `number`",
"description": "The quantity of the Line Item that has been fulfilled.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_total",
"type": "`null` \\| `number`",
"description": "The total of the gift card of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "has_shipping",
"type": "`null` \\| `boolean`",
"description": "Flag to indicate if the Line Item has fulfillment associated with it.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The line item's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "includes_tax",
"type": "`boolean`",
"description": "Indicates if the line item unit\\_price include tax",
"optional": false,
"defaultValue": "false",
"expandable": false,
"featureFlag": "tax_inclusive_pricing",
"children": []
},
{
"name": "is_giftcard",
"type": "`boolean`",
"description": "Flag to indicate if the Line Item is a Gift Card.",
"optional": false,
"defaultValue": "false",
"expandable": false,
"children": []
},
{
"name": "is_return",
"type": "`boolean`",
"description": "Is the item being returned",
"optional": false,
"defaultValue": "false",
"expandable": false,
"children": []
},
{
"name": "metadata",
"type": "`Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "order",
"type": "[Order](Order.mdx)",
"description": "The details of the order that the line item may belongs to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "order_edit",
"type": "`null` \\| [OrderEdit](OrderEdit.mdx)",
"description": "The details of the order edit.",
"optional": true,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "order_edit_id",
"type": "`null` \\| `string`",
"description": "The ID of the order edit that the item may belong to.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "order_id",
"type": "`null` \\| `string`",
"description": "The ID of the order that the line item may belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "original_item_id",
"type": "`null` \\| `string`",
"description": "The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "original_tax_total",
"type": "`null` \\| `number`",
"description": "The original tax total amount of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "original_total",
"type": "`null` \\| `number`",
"description": "The original total amount of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "product_id",
"type": "`null` \\| `string`",
"description": "",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "quantity",
"type": "`number`",
"description": "The quantity of the content in the Line Item.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "raw_discount_total",
"type": "`null` \\| `number`",
"description": "The total of discount of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refundable",
"type": "`null` \\| `number`",
"description": "The amount that can be refunded from the given Line Item. Takes taxes and discounts into consideration.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "returned_quantity",
"type": "`null` \\| `number`",
"description": "The quantity of the Line Item that has been returned.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipped_quantity",
"type": "`null` \\| `number`",
"description": "The quantity of the Line Item that has been shipped.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "should_merge",
"type": "`boolean`",
"description": "Flag to indicate if new Line Items with the same variant should be merged or added as an additional Line Item.",
"optional": false,
"defaultValue": "true",
"expandable": false,
"children": []
},
{
"name": "subtotal",
"type": "`null` \\| `number`",
"description": "The subtotal of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "swap",
"type": "[Swap](Swap.mdx)",
"description": "The details of the swap that the line item may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "swap_id",
"type": "`string`",
"description": "The ID of the swap that the line item may belong to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "tax_lines",
"type": "[LineItemTaxLine](LineItemTaxLine.mdx)[]",
"description": "The details of the item's tax lines.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "tax_total",
"type": "`null` \\| `number`",
"description": "The total of tax of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "thumbnail",
"type": "`null` \\| `string`",
"description": "A URL string to a small image of the contents of the Line Item.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "title",
"type": "`string`",
"description": "The title of the Line Item.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "total",
"type": "`null` \\| `number`",
"description": "The total amount of the line item",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "unit_price",
"type": "`number`",
"description": "The price of one unit of the content in the Line Item. This should be in the currency defined by the Cart/Order/Swap/Claim that the Line Item belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "variant",
"type": "[ProductVariant](ProductVariant.mdx)",
"description": "The details of the product variant that this item was created from.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "variant_id",
"type": "`null` \\| `string`",
"description": "The id of the Product Variant contained in the Line Item.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
},
{
"name": "order",
"type": "[Order](Order.mdx)",
"description": "An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "billing_address",
"type": "[Address](Address.mdx)",
"description": "The details of the billing address associated with the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "billing_address_id",
"type": "`string`",
"description": "The ID of the billing address associated with the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "canceled_at",
"type": "`Date`",
"description": "The date the order was canceled on.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "cart",
"type": "[Cart](Cart.mdx)",
"description": "The details of the cart associated with the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "cart_id",
"type": "`string`",
"description": "The ID of the cart associated with the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "claims",
"type": "[ClaimOrder](ClaimOrder.mdx)[]",
"description": "The details of the claims created for the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "currency",
"type": "[Currency](Currency.mdx)",
"description": "The details of the currency used in the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "currency_code",
"type": "`string`",
"description": "The 3 character currency code that is used in the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "customer",
"type": "[Customer](Customer.mdx)",
"description": "The details of the customer associated with the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "customer_id",
"type": "`string`",
"description": "The ID of the customer associated with the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discount_total",
"type": "`number`",
"description": "The total of discount rounded",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discounts",
"type": "[Discount](Discount.mdx)[]",
"description": "The details of the discounts applied on the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "display_id",
"type": "`number`",
"description": "The order's display ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "draft_order",
"type": "[DraftOrder](DraftOrder.mdx)",
"description": "The details of the draft order this order was created from.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "draft_order_id",
"type": "`string`",
"description": "The ID of the draft order this order was created from.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "edits",
"type": "[OrderEdit](OrderEdit.mdx)[]",
"description": "The details of the order edits done on the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "email",
"type": "`string`",
"description": "The email associated with the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "external_id",
"type": "`null` \\| `string`",
"description": "The ID of an external order.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "fulfillment_status",
"type": "[FulfillmentStatus](../enums/FulfillmentStatus.mdx)",
"description": "The order's fulfillment status",
"optional": false,
"defaultValue": "not_fulfilled",
"expandable": false,
"children": []
},
{
"name": "fulfillments",
"type": "[Fulfillment](Fulfillment.mdx)[]",
"description": "The details of the fulfillments created for the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "gift_card_tax_total",
"type": "`number`",
"description": "The total of gift cards with taxes",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_total",
"type": "`number`",
"description": "The total of gift cards",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_transactions",
"type": "[GiftCardTransaction](GiftCardTransaction.mdx)[]",
"description": "The gift card transactions made in the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "gift_cards",
"type": "[GiftCard](GiftCard.mdx)[]",
"description": "The details of the gift card used in the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The order's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "idempotency_key",
"type": "`string`",
"description": "Randomly generated key used to continue the processing of the order in case of failure.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "item_tax_total",
"type": "`null` \\| `number`",
"description": "The tax total applied on items",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[LineItem](LineItem.mdx)[]",
"description": "The details of the line items that belong to the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "metadata",
"type": "`Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "no_notification",
"type": "`boolean`",
"description": "Flag for describing whether or not notifications related to this should be send.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "object",
"type": "`\"order\"`",
"description": "",
"optional": false,
"defaultValue": "\"order\"",
"expandable": false,
"children": []
},
{
"name": "paid_total",
"type": "`number`",
"description": "The total amount paid",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "payment_status",
"type": "[PaymentStatus](../enums/PaymentStatus.mdx)",
"description": "The order's payment status",
"optional": false,
"defaultValue": "not_paid",
"expandable": false,
"children": []
},
{
"name": "payments",
"type": "[Payment](Payment.mdx)[]",
"description": "The details of the payments used in the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "raw_discount_total",
"type": "`number`",
"description": "The total of discount",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refundable_amount",
"type": "`number`",
"description": "The amount that can be refunded",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refunded_total",
"type": "`number`",
"description": "The total amount refunded if the order is returned.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refunds",
"type": "[Refund](Refund.mdx)[]",
"description": "The details of the refunds created for the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "region",
"type": "[Region](Region.mdx)",
"description": "The details of the region this order was created in.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "region_id",
"type": "`string`",
"description": "The ID of the region this order was created in.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "returnable_items",
"type": "[LineItem](LineItem.mdx)[]",
"description": "The details of the line items that are returnable as part of the order, swaps, or claims",
"optional": true,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "returns",
"type": "[Return](Return.mdx)[]",
"description": "The details of the returns created for the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "sales_channel",
"type": "[SalesChannel](SalesChannel.mdx)",
"description": "The details of the sales channel this order belongs to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "sales_channel_id",
"type": "`null` \\| `string`",
"description": "The ID of the sales channel this order belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_address",
"type": "[Address](Address.mdx)",
"description": "The details of the shipping address associated with the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_address_id",
"type": "`string`",
"description": "The ID of the shipping address associated with the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_methods",
"type": "[ShippingMethod](ShippingMethod.mdx)[]",
"description": "The details of the shipping methods used in the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_tax_total",
"type": "`null` \\| `number`",
"description": "The tax total applied on shipping",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_total",
"type": "`number`",
"description": "The total of shipping",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "status",
"type": "[OrderStatus](../enums/OrderStatus.mdx)",
"description": "The order's status",
"optional": false,
"defaultValue": "pending",
"expandable": false,
"children": []
},
{
"name": "subtotal",
"type": "`number`",
"description": "The subtotal of the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "swaps",
"type": "[Swap](Swap.mdx)[]",
"description": "The details of the swaps created for the order.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "tax_rate",
"type": "`null` \\| `number`",
"description": "The order's tax rate",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "tax_total",
"type": "`null` \\| `number`",
"description": "The total of tax",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "total",
"type": "`number`",
"description": "The total amount of the order",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
},
{
"name": "fulfillment",
"type": "[Fulfillment](Fulfillment.mdx)",
"description": "A Fulfillment is created once an admin can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a fulfillment provider, which typically integrates a third-party shipping service. Fulfillments can be associated with orders, claims, swaps, and returns.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "canceled_at",
"type": "`Date`",
"description": "The date with timezone at which the Fulfillment was canceled.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "claim_order",
"type": "[ClaimOrder](ClaimOrder.mdx)",
"description": "The details of the claim that the fulfillment may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "claim_order_id",
"type": "`string`",
"description": "The ID of the Claim that the Fulfillment belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "data",
"type": "`Record<string, unknown>`",
"description": "This contains all the data necessary for the Fulfillment provider to handle the fulfillment.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The fulfillment's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "idempotency_key",
"type": "`string`",
"description": "Randomly generated key used to continue the completion of the fulfillment in case of failure.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[FulfillmentItem](FulfillmentItem.mdx)[]",
"description": "The Fulfillment Items in the Fulfillment. These hold information about how many of each Line Item has been fulfilled.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "location_id",
"type": "`null` \\| `string`",
"description": "The ID of the stock location the fulfillment will be shipped from",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "metadata",
"type": "`Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "no_notification",
"type": "`boolean`",
"description": "Flag for describing whether or not notifications related to this should be sent.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "order",
"type": "[Order](Order.mdx)",
"description": "The details of the order that the fulfillment may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "order_id",
"type": "`string`",
"description": "The ID of the Order that the Fulfillment belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "provider",
"type": "[FulfillmentProvider](FulfillmentProvider.mdx)",
"description": "The details of the fulfillment provider responsible for handling the fulfillment.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "provider_id",
"type": "`string`",
"description": "The ID of the Fulfillment Provider responsible for handling the fulfillment.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipped_at",
"type": "`Date`",
"description": "The date with timezone at which the Fulfillment was shipped.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "swap",
"type": "[Swap](Swap.mdx)",
"description": "The details of the swap that the fulfillment may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "swap_id",
"type": "`string`",
"description": "The ID of the Swap that the Fulfillment belongs to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "tracking_links",
"type": "[TrackingLink](TrackingLink.mdx)[]",
"description": "The Tracking Links that can be used to track the status of the Fulfillment. These will usually be provided by the Fulfillment Provider.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "tracking_numbers",
"type": "`string`[]",
"description": "The tracking numbers that can be used to track the status of the fulfillment.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;[FulfillmentProviderData](../types/FulfillmentProviderData.mdx)&#62;",
"optional": false,
"defaultValue": "",
"description": "The data that will be stored in the `data` attribute of the created fulfillment.",
"expandable": false,
"children": [
{
"name": "FulfillmentProviderData",
"type": "`Record<string, unknown>`",
"description": "",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### createReturn
Fulfillment providers can also be used to return products. A shipping option can be used for returns if the `is_return` property is true or if an admin creates a Return Shipping Option from the settings.
This method is used when the admin [creates a return request](https://docs.medusajs.com/api/admin#orders\_postordersorderreturns) for an order,
[creates a swap](https://docs.medusajs.com/api/admin#orders\_postordersorderswaps) for an order, or when the
[customer creates a return of their order](https://docs.medusajs.com/api/store#returns\_postreturns). The fulfillment is created automatically for the order return.
#### Example
This is the basic implementation of the method for a fulfillment provider that does not contact with a third-party provider to fulfill the return:
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async createReturn(
returnOrder: CreateReturnType
): Promise<Record<string, unknown>> {
return {}
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "returnOrder",
"type": "[CreateReturnType](../types/CreateReturnType.mdx)",
"description": "the return that the fulfillment is being created for.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "claim_order",
"type": "[ClaimOrder](ClaimOrder.mdx)",
"description": "The details of the claim that the return may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "claim_order_id",
"type": "`null` \\| `string`",
"description": "The ID of the claim that the return may belong to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The return's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "idempotency_key",
"type": "`null` \\| `string`",
"description": "Randomly generated key used to continue the completion of the return in case of failure.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[ReturnItem](ReturnItem.mdx)[]",
"description": "The details of the items that the customer is returning.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "location_id",
"type": "`null` \\| `string`",
"description": "The ID of the stock location the return will be added back.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "metadata",
"type": "`null` \\| `Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "no_notification",
"type": "`null` \\| `boolean`",
"description": "When set to true, no notification will be sent related to this return.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "order",
"type": "[Order](Order.mdx)",
"description": "The details of the order that the return was created for.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "order_id",
"type": "`null` \\| `string`",
"description": "The ID of the order that the return was created for.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "received_at",
"type": "`Date`",
"description": "The date with timezone at which the return was received.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refund_amount",
"type": "`number`",
"description": "The amount that should be refunded as a result of the return.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_data",
"type": "`Record<string, unknown>`",
"description": "Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_method",
"type": "[ShippingMethod](ShippingMethod.mdx)",
"description": "The details of the Shipping Method that will be used to send the Return back. Can be null if the Customer will handle the return shipment themselves.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "status",
"type": "[ReturnStatus](../enums/ReturnStatus.mdx)",
"description": "Status of the Return.",
"optional": false,
"defaultValue": "requested",
"expandable": false,
"children": []
},
{
"name": "swap",
"type": "[Swap](Swap.mdx)",
"description": "The details of the swap that the return may belong to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "swap_id",
"type": "`null` \\| `string`",
"description": "The ID of the swap that the return may belong to.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;Record&#60;string, unknown&#62;&#62;",
"optional": false,
"defaultValue": "",
"description": "Used to set the value of the `shipping_data` attribute of the return being created.",
"expandable": false,
"children": [
{
"name": "Record",
"type": "`Record<string, unknown>`",
"optional": false,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### getFulfillmentDocuments
This method is used to retrieve any documents associated with a fulfillment. This method isn't used by default in the backend, but you can use it for custom use cases such as allowing admins to download these documents.
#### Example
```ts
class MyFulfillmentService extends FulfillmentService {
// ...
async getFulfillmentDocuments(
data: Record<string, unknown>
): Promise<any> {
// assuming you contact a client to
// retrieve the document
return this.client.getFulfillmentDocuments()
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "[FulfillmentProviderData](../types/FulfillmentProviderData.mdx)",
"description": "The `data` attribute of the fulfillment that you're retrieving the documents for.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any&#62;",
"optional": false,
"defaultValue": "",
"description": "There are no restrictions on the returned response. If your fulfillment provider doesn't provide this functionality, you can leave the method empty or through an error.",
"expandable": false,
"children": [
{
"name": "any",
"type": "`any`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### getFulfillmentOptions
This method is used when retrieving the list of fulfillment options available in a region, particularly by the [List Fulfillment Options API Route](https://docs.medusajs.com/api/admin#regions\_getregionsregionfulfillmentoptions).
For example, if you’re integrating UPS as a fulfillment provider, you might support two fulfillment options: UPS Express Shipping and UPS Access Point. Each of these options can have different data associated with them.
#### Example
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async getFulfillmentOptions(): Promise<any[]> {
return [
{
id: "my-fulfillment",
},
{
id: "my-fulfillment-dynamic",
},
]
}
}
```
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any[]&#62;",
"optional": false,
"defaultValue": "",
"description": "The list of fulfillment options. These options don't have any required format. Later on, these options can be used when creating a shipping option,\nsuch as when using the [Create Shipping Option API Route](https://docs.medusajs.com/api/admin#shipping-options\\_postshippingoptions). The chosen fulfillment option, which is one of the\nitems in the array returned by this method, will be set in the `data` object of the shipping option.",
"expandable": false,
"children": [
{
"name": "any[]",
"type": "`any`[]",
"optional": false,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### getReturnDocuments
This method is used to retrieve any documents associated with a return. This method isn't used by default in the backend, but you can use it for custom use cases such as allowing admins to download these documents.
#### Example
```ts
class MyFulfillmentService extends FulfillmentService {
// ...
async getReturnDocuments(
data: Record<string, unknown>
): Promise<any> {
// assuming you contact a client to
// retrieve the document
return this.client.getReturnDocuments()
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "`Record<string, unknown>`",
"description": "The data attribute of the return that you're retrieving the documents for.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any&#62;",
"optional": false,
"defaultValue": "",
"description": "There are no restrictions on the returned response. If your fulfillment provider doesn't provide this functionality, you can leave the method empty or through an error.",
"expandable": false,
"children": [
{
"name": "any",
"type": "`any`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### getShipmentDocuments
This method is used to retrieve any documents associated with a shipment. This method isn't used by default in the backend, but you can use it for custom use cases such as allowing admins to download these documents.
#### Example
```ts
class MyFulfillmentService extends FulfillmentService {
// ...
async getShipmentDocuments(
data: Record<string, unknown>
): Promise<any> {
// assuming you contact a client to
// retrieve the document
return this.client.getShipmentDocuments()
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "`Record<string, unknown>`",
"description": "The `data` attribute of the shipment that you're retrieving the documents for.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any&#62;",
"optional": false,
"defaultValue": "",
"description": "There are no restrictions on the returned response. If your fulfillment provider doesn't provide this functionality, you can leave the method empty or through an error.",
"expandable": false,
"children": [
{
"name": "any",
"type": "`any`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### retrieveDocuments
This method is used to retrieve any documents associated with an order and its fulfillments. This method isn't used by default in the backend, but you can use it for
custom use cases such as allowing admins to download these documents.
#### Example
```ts
class MyFulfillmentService extends FulfillmentService {
// ...
async retrieveDocuments(
fulfillmentData: Record<string, unknown>,
documentType: "invoice" | "label"
): Promise<any> {
// assuming you contact a client to
// retrieve the document
return this.client.getDocuments()
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "fulfillmentData",
"type": "`Record<string, unknown>`",
"description": "The `data` attribute of the order's fulfillment.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "documentType",
"type": "`\"label\"` \\| `\"invoice\"`",
"description": "The type of document to retrieve.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;any&#62;",
"optional": false,
"defaultValue": "",
"description": "There are no restrictions on the returned response. If your fulfillment provider doesn't provide this functionality, you can leave the method empty or through an error.",
"expandable": false,
"children": [
{
"name": "any",
"type": "`any`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### validateFulfillmentData
This method is called when a shipping method is created. This typically happens when the customer chooses a shipping option during checkout, when a shipping method is created
for an order return, or in other similar cases. The shipping option and its data are validated before the shipping method is created.
You can use the provided parameters to validate the chosen shipping option. For example, you can check if the `data` object passed as a second parameter includes all data needed to
fulfill the shipment later on.
If any of the data is invalid, you can throw an error. This error will stop Medusa from creating a shipping method and the error message will be returned as a result of the API Route.
#### Example
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async validateFulfillmentData(
optionData: Record<string, unknown>,
data: Record<string, unknown>,
cart: Cart
): Promise<Record<string, unknown>> {
if (data.id !== "my-fulfillment") {
throw new Error("invalid data")
}
return {
...data,
}
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "optionData",
"type": "[ShippingOptionData](../types/ShippingOptionData.mdx)",
"description": "The data object of the shipping option selected when creating the shipping method.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "data",
"type": "[FulfillmentProviderData](../types/FulfillmentProviderData.mdx)",
"description": "The `data` object passed in the body of the request.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "cart",
"type": "[Cart](Cart.mdx)",
"description": "A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": [
{
"name": "billing_address",
"type": "[Address](Address.mdx)",
"description": "The details of the billing address associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "billing_address_id",
"type": "`string`",
"description": "The billing address's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "completed_at",
"type": "`Date`",
"description": "The date with timezone at which the cart was completed.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "context",
"type": "`Record<string, unknown>`",
"description": "The context of the cart which can include info like IP or user agent.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "created_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was created.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "customer",
"type": "[Customer](Customer.mdx)",
"description": "The details of the customer the cart belongs to.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "customer_id",
"type": "`string`",
"description": "The customer's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "deleted_at",
"type": "`null` \\| `Date`",
"description": "The date with timezone at which the resource was deleted.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discount_total",
"type": "`number`",
"description": "The total of discount rounded",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "discounts",
"type": "[Discount](Discount.mdx)[]",
"description": "An array of details of all discounts applied to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "email",
"type": "`string`",
"description": "The email associated with the cart",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_tax_total",
"type": "`number`",
"description": "The total of gift cards with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_card_total",
"type": "`number`",
"description": "The total of gift cards",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "gift_cards",
"type": "[GiftCard](GiftCard.mdx)[]",
"description": "An array of details of all gift cards applied to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "id",
"type": "`string`",
"description": "The cart's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "idempotency_key",
"type": "`string`",
"description": "Randomly generated key used to continue the completion of a cart in case of failure.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "item_tax_total",
"type": "`null` \\| `number`",
"description": "The total of items with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "items",
"type": "[LineItem](LineItem.mdx)[]",
"description": "The line items added to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "metadata",
"type": "`Record<string, unknown>`",
"description": "An optional key-value map with additional details",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "object",
"type": "`\"cart\"`",
"description": "",
"optional": false,
"defaultValue": "\"cart\"",
"expandable": false,
"children": []
},
{
"name": "payment",
"type": "[Payment](Payment.mdx)",
"description": "The details of the payment associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "payment_authorized_at",
"type": "`Date`",
"description": "The date with timezone at which the payment was authorized.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "payment_id",
"type": "`string`",
"description": "The payment's ID if available",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "payment_session",
"type": "`null` \\| [PaymentSession](PaymentSession.mdx)",
"description": "The details of the selected payment session in the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "payment_sessions",
"type": "[PaymentSession](PaymentSession.mdx)[]",
"description": "The details of all payment sessions created on the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "raw_discount_total",
"type": "`number`",
"description": "The total of discount",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refundable_amount",
"type": "`number`",
"description": "The amount that can be refunded",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "refunded_total",
"type": "`number`",
"description": "The total amount refunded if the order associated with this cart is returned.",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "region",
"type": "[Region](Region.mdx)",
"description": "The details of the region associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "region_id",
"type": "`string`",
"description": "The region's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "sales_channel",
"type": "[SalesChannel](SalesChannel.mdx)",
"description": "The details of the sales channel associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "sales_channel_id",
"type": "`null` \\| `string`",
"description": "The sales channel ID the cart is associated with.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_address",
"type": "`null` \\| [Address](Address.mdx)",
"description": "The details of the shipping address associated with the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_address_id",
"type": "`string`",
"description": "The shipping address's ID",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_methods",
"type": "[ShippingMethod](ShippingMethod.mdx)[]",
"description": "The details of the shipping methods added to the cart.",
"optional": false,
"defaultValue": "",
"expandable": true,
"children": []
},
{
"name": "shipping_tax_total",
"type": "`null` \\| `number`",
"description": "The total of shipping with taxes",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "shipping_total",
"type": "`number`",
"description": "The total of shipping",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "subtotal",
"type": "`number`",
"description": "The subtotal of the cart",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "tax_total",
"type": "`null` \\| `number`",
"description": "The total of tax",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "total",
"type": "`number`",
"description": "The total amount of the cart",
"optional": true,
"defaultValue": "",
"expandable": false,
"children": []
},
{
"name": "type",
"type": "[CartType](../enums/CartType.mdx)",
"description": "The cart's type.",
"optional": false,
"defaultValue": "default",
"expandable": false,
"children": []
},
{
"name": "updated_at",
"type": "`Date`",
"description": "The date with timezone at which the resource was updated.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;Record&#60;string, unknown&#62;&#62;",
"optional": false,
"defaultValue": "",
"description": "The data that will be stored in the `data` property of the shipping method to be created.\nMake sure the value you return contains everything you need to fulfill the shipment later on. The returned value may also be used to calculate the price of the shipping method\nif it doesn't have a set price. It will be passed along to the [calculatePrice](../interfaces/FulfillmentService.mdx#calculateprice) method.",
"expandable": false,
"children": [
{
"name": "Record",
"type": "`Record<string, unknown>`",
"optional": false,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
___
### validateOption
Once the admin creates the shipping option, the data of the shipping option will be validated first using this method. This method is called when the [Create Shipping Option API Route](https://docs.medusajs.com/api/admin#shipping-options\_postshippingoptions) is used.
#### Example
For example, you can use this method to ensure that the `id` in the `data` object is correct:
```ts
class MyFulfillmentService extends AbstractFulfillmentService {
// ...
async validateOption(
data: Record<string, unknown>
): Promise<boolean> {
return data.id == "my-fulfillment"
}
}
```
#### Parameters
<ParameterTypes parameters={[
{
"name": "data",
"type": "[ShippingOptionData](../types/ShippingOptionData.mdx)",
"description": "the data object that is sent in the body of the request, basically, the data object of the shipping option. You can use this data to validate the shipping option before it is saved.",
"optional": false,
"defaultValue": "",
"expandable": false,
"children": []
}
]} />
#### Returns
<ParameterTypes parameters={[
{
"name": "Promise",
"type": "Promise&#60;boolean&#62;",
"optional": false,
"defaultValue": "",
"description": "Whether the fulfillment option is valid. If the returned value is false, an error is thrown and the shipping option will not be saved.",
"expandable": false,
"children": [
{
"name": "boolean",
"type": "`boolean`",
"optional": true,
"defaultValue": "",
"description": "",
"expandable": false,
"children": []
}
]
}
]} />
Reference in New Issue View Git Blame Copy Permalink