chore(docs): Generated References (#6222)
Generated the following references: - `entities` - `file` - `fulfillment` - `inventory` - `js_client` - `medusa` - `medusa_config` - `medusa_react` - `modules` - `notification` - `payment` - `price_selection` - `pricing` - `product` - `search` - `services` - `stock_location` - `tax` - `tax_calculation` - `types` - `workflows` Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com> Co-authored-by: Shahed Nasser <27354907+shahednasser@users.noreply.github.com>
This commit is contained in:
1463 files changed
+359543
-335590
No files matched your search
+161
-160
@@ -49,6 +49,7 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
## 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.
|
||||
|
||||
@@ -71,12 +72,130 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"container","type":"[MedusaContainer](../../medusa/types/medusa.MedusaContainer-2.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":"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":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"container","type":"[MedusaContainer](../../medusa/types/medusa.MedusaContainer-2.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":"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":[]}]} sectionTitle="new AbstractFulfillmentService"/>
|
||||
|
||||
___
|
||||
|
||||
## Methods
|
||||
|
||||
### 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<any[]>","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":[]}]}]} sectionTitle="getFulfillmentOptions"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` object passed in the body of the request.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The customer's cart details. It may be empty if the shipping method isn't associated with a cart, such as when it's associated with a claim.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The cart's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","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":"object","type":"`\"cart\"`","description":"","optional":false,"defaultValue":"\"cart\"","expandable":false,"children":[]},{"name":"email","type":"`string`","description":"The email associated with the cart","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address_id","type":"`string`","description":"The billing address's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address","type":"[Address](../../entities/classes/entities.Address.mdx)","description":"The details of the billing 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_address","type":"`null` \\| [Address](../../entities/classes/entities.Address.mdx)","description":"The details of the shipping address associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"The line items added to 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":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The details of the region associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"discounts","type":"[Discount](../../entities/classes/entities.Discount.mdx)[]","description":"An array of details of all discounts applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"gift_cards","type":"[GiftCard](../../entities/classes/entities.GiftCard.mdx)[]","description":"An array of details of all gift cards applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"customer_id","type":"`string`","description":"The customer's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The details of the customer the cart belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_session","type":"`null` \\| [PaymentSession](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_id","type":"`string`","description":"The payment's ID if available","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"payment","type":"[Payment](../../entities/classes/entities.Payment.mdx)","description":"The details of the payment associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"shipping_methods","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)[]","description":"The details of the Line truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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](fulfillment.AbstractFulfillmentService.mdx#calculateprice) method.","expandable":false,"children":[{"name":"Record","type":"`Record<string, unknown>`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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":[]}]} sectionTitle="validateOption"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<boolean>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="validateOption"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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":[]}]} sectionTitle="canCalculate"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<boolean>","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](fulfillment.AbstractFulfillmentService.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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="canCalculate"/>
|
||||
|
||||
### calculatePrice
|
||||
|
||||
This method is used in different places, including:
|
||||
@@ -119,63 +238,11 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"optionData","type":"[ShippingOptionData](../../medusa/types/medusa.ShippingOptionData.mdx)","description":"The `data` object of the selected shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.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](fulfillment.AbstractFulfillmentService.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](../../entities/classes/entities.Cart.mdx)","description":"Either the Cart or the Order object.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"billing_address","type":"[Address](../../entities/classes/entities.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](../../entities/classes/entities.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":"discounts","type":"[Discount](../../entities/classes/entities.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_cards","type":"[GiftCard](../../entities/classes/entities.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":"items","type":"[LineItem](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optionaLine truncated
|
||||
<ParameterTypes parameters={[{"name":"optionData","type":"[ShippingOptionData](../../medusa/types/medusa.ShippingOptionData.mdx)","description":"The `data` object of the selected shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.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](fulfillment.AbstractFulfillmentService.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](../../entities/classes/entities.Cart.mdx)","description":"Either the Cart or the Order object.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The cart's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","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":"object","type":"`\"cart\"`","description":"","optional":false,"defaultValue":"\"cart\"","expandable":false,"children":[]},{"name":"email","type":"`string`","description":"The email associated with the cart","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address_id","type":"`string`","description":"The billing address's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address","type":"[Address](../../entities/classes/entities.Address.mdx)","description":"The details of the billing 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_address","type":"`null` \\| [Address](../../entities/classes/entities.Address.mdx)","description":"The details of the shipping address associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"The line items added to 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":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The details of the region associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"discounts","type":"[Discount](../../entities/classes/entities.Discount.mdx)[]","description":"An array of details of all discounts applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"gift_cards","type":"[GiftCard](../../entities/classes/entities.GiftCard.mdx)[]","description":"An array of details of all gift cards applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"customer_id","type":"`string`","description":"The customer's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The details of the customer the cart belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_session","type":"`null` \\| [PaymentSession](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_id","type":"`string`","description":"The payment's ID if available","optional":false,"defauLine truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<number>","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":false,"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](../../medusa/types/medusa.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<boolean>","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](fulfillment.AbstractFulfillmentService.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":false,"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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment being canceled","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"The method isn't expected to return any specific data.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<number>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="calculatePrice"/>
|
||||
|
||||
### createFulfillment
|
||||
|
||||
@@ -203,11 +270,38 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[ShippingMethodData](../../medusa/types/medusa.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](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.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":"fulfilled_quantity","type":"`null` \\| `number`","description":"The quantity of the Line Item that has been fulfilled.","optional":false,"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](../../entities/classes/entities.Order.mdx)","description":"The details of the order that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"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":"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":"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","expanLine truncated
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[ShippingMethodData](../../medusa/types/medusa.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](../../entities/classes/entities.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":"id","type":"`string`","description":"The line item's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","optional":false,"defaultValue":"","expandable":false,"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":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The details of the cart that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"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":"order","type":"[Order](../../entities/classes/entities.Order.mdx)","description":"The details of the order that the line item may belongs 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":"swap","type":"[Swap](../../entities/classes/entities.Swap.mdx)","description":"The details of the swap 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":"claim_order","type":"[ClaimOrder](../../entities/classes/entities.ClaimOrder.mdx)","description":"The details of the claim that the line item may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"tax_lines","type":"[LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx)[]","description":"The details of the item's tax lines.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"adjustments","type":"[LineItemAdjustment](../../entities/classes/entities.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":"title","type":"`string`","description":"The title of the Line Item.","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":"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":"is_return","type":"`boolean`","description":"Is the item being returned","optional":false,"defaultValue":"false","expandable":false,"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":"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":"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":"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":"unit_price","type":"`number`","description":"The price of one unit of the content in the Line Item. This should be in the currencLine truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)>","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":[]}]}]} sectionTitle="createFulfillment"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment being canceled","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="cancelFulfillment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"The method isn't expected to return any specific data.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="cancelFulfillment"/>
|
||||
|
||||
### createReturn
|
||||
|
||||
@@ -233,11 +327,11 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"returnOrder","type":"[CreateReturnType](../../medusa/types/medusa.CreateReturnType.mdx)","description":"the return that the fulfillment is being created for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"returnOrder","type":"[CreateReturnType](../../medusa/types/medusa.CreateReturnType.mdx)","description":"the return that the fulfillment is being created for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createReturn"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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":[]}]}]} sectionTitle="createReturn"/>
|
||||
|
||||
### getFulfillmentDocuments
|
||||
|
||||
@@ -260,38 +354,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment that you're retrieving the documents for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment that you're retrieving the documents for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"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<any[]>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
### getReturnDocuments
|
||||
|
||||
@@ -314,11 +381,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### 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":[]}]} />
|
||||
<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":[]}]} sectionTitle="getReturnDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getReturnDocuments"/>
|
||||
|
||||
### getShipmentDocuments
|
||||
|
||||
@@ -341,11 +408,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### 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":[]}]} />
|
||||
<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":[]}]} sectionTitle="getShipmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getShipmentDocuments"/>
|
||||
|
||||
### retrieveDocuments
|
||||
|
||||
@@ -370,77 +437,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### 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":[]}]} />
|
||||
<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":[]}]} sectionTitle="retrieveDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"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](../../medusa/types/medusa.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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` object passed in the body of the request.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The customer's cart details. It may be empty if the shipping method isn't associated with a cart, such as when it's associated with a claim.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"billing_address","type":"[Address](../../entities/classes/entities.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](../../entities/classes/entities.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":"discounts","type":"[Discount](../../entities/classes/entities.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_cards","type":"[GiftCard](../../entities/classes/entities.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":"items","type":"[LineItem](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The Line truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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](fulfillment.AbstractFulfillmentService.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](../../medusa/types/medusa.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<boolean>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="retrieveDocuments"/>
|
||||
|
||||
---
|
||||
|
||||
|
||||
+184
-184
@@ -45,7 +45,7 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
## Properties
|
||||
|
||||
<ParameterTypes parameters={[{"name":"__container__","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"manager_","type":"`EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionManager_","type":"`undefined` \\| `EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__configModule__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"__moduleDeclaration__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"manager_","type":"`EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionManager_","type":"`undefined` \\| `EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__container__","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__configModule__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"__moduleDeclaration__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="FulfillmentService"/>
|
||||
|
||||
___
|
||||
|
||||
@@ -55,29 +55,129 @@ ___
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"EntityManager","type":"`EntityManager`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"EntityManager","type":"`EntityManager`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="activeManager_"/>
|
||||
|
||||
___
|
||||
|
||||
## Methods
|
||||
|
||||
### atomicPhase\_
|
||||
### getFulfillmentOptions
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
#### Type Parameters
|
||||
#### Example
|
||||
|
||||
<ParameterTypes parameters={[{"name":"TResult","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"TError","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"work","type":"(`transactionManager`: `EntityManager`) => Promise<TResult>","description":"the transactional work to be done","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationOrErrorHandler","type":"`IsolationLevel` \\| (`error`: TError) => Promise<void \\| TResult>","description":"the isolation level to be used for the work.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"maybeErrorHandlerOrDontFail","type":"(`error`: TError) => Promise<void \\| TResult>","description":"Potential error handler","optional":true,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
```ts
|
||||
class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
// ...
|
||||
async getFulfillmentOptions(): Promise<any[]> {
|
||||
return [
|
||||
{
|
||||
id: "my-fulfillment",
|
||||
},
|
||||
{
|
||||
id: "my-fulfillment-dynamic",
|
||||
},
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<TResult>","optional":false,"defaultValue":"","description":"the result of the transactional work","expandable":false,"children":[{"name":"TResult","type":"TResult","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any[]>","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":[]}]}]} sectionTitle="getFulfillmentOptions"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` object passed in the body of the request.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The customer's cart details. It may be empty if the shipping method isn't associated with a cart, such as when it's associated with a claim.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The cart's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","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":"object","type":"`\"cart\"`","description":"","optional":false,"defaultValue":"\"cart\"","expandable":false,"children":[]},{"name":"email","type":"`string`","description":"The email associated with the cart","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address_id","type":"`string`","description":"The billing address's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address","type":"[Address](../../entities/classes/entities.Address.mdx)","description":"The details of the billing 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_address","type":"`null` \\| [Address](../../entities/classes/entities.Address.mdx)","description":"The details of the shipping address associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"The line items added to 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":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The details of the region associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"discounts","type":"[Discount](../../entities/classes/entities.Discount.mdx)[]","description":"An array of details of all discounts applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"gift_cards","type":"[GiftCard](../../entities/classes/entities.GiftCard.mdx)[]","description":"An array of details of all gift cards applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"customer_id","type":"`string`","description":"The customer's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The details of the customer the cart belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_session","type":"`null` \\| [PaymentSession](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_id","type":"`string`","description":"The payment's ID if available","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"payment","type":"[Payment](../../entities/classes/entities.Payment.mdx)","description":"The details of the payment associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"shipping_methods","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)[]","description":"The details of the Line truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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](fulfillment.FulfillmentService.mdx#calculateprice) method.","expandable":false,"children":[{"name":"Record","type":"`Record<string, unknown>`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="validateFulfillmentData"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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":[]}]} sectionTitle="validateOption"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<boolean>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="validateOption"/>
|
||||
|
||||
### 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](../../medusa/types/medusa.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":[]}]} sectionTitle="canCalculate"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<boolean>","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](fulfillment.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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="canCalculate"/>
|
||||
|
||||
### calculatePrice
|
||||
|
||||
@@ -121,63 +221,11 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"optionData","type":"[ShippingOptionData](../../medusa/types/medusa.ShippingOptionData.mdx)","description":"The `data` object of the selected shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.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](fulfillment.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](../../entities/classes/entities.Cart.mdx)","description":"Either the Cart or the Order object.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"billing_address","type":"[Address](../../entities/classes/entities.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](../../entities/classes/entities.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":"discounts","type":"[Discount](../../entities/classes/entities.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_cards","type":"[GiftCard](../../entities/classes/entities.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":"items","type":"[LineItem](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":falseLine truncated
|
||||
<ParameterTypes parameters={[{"name":"optionData","type":"[ShippingOptionData](../../medusa/types/medusa.ShippingOptionData.mdx)","description":"The `data` object of the selected shipping option.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.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](fulfillment.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](../../entities/classes/entities.Cart.mdx)","description":"Either the Cart or the Order object.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The cart's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","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":"object","type":"`\"cart\"`","description":"","optional":false,"defaultValue":"\"cart\"","expandable":false,"children":[]},{"name":"email","type":"`string`","description":"The email associated with the cart","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address_id","type":"`string`","description":"The billing address's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"billing_address","type":"[Address](../../entities/classes/entities.Address.mdx)","description":"The details of the billing 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_address","type":"`null` \\| [Address](../../entities/classes/entities.Address.mdx)","description":"The details of the shipping address associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"The line items added to 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":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The details of the region associated with the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"discounts","type":"[Discount](../../entities/classes/entities.Discount.mdx)[]","description":"An array of details of all discounts applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"gift_cards","type":"[GiftCard](../../entities/classes/entities.GiftCard.mdx)[]","description":"An array of details of all gift cards applied to the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"customer_id","type":"`string`","description":"The customer's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The details of the customer the cart belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_session","type":"`null` \\| [PaymentSession](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_id","type":"`string`","description":"The payment's ID if available","optional":false,"defaultValue"Line truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<number>","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":false,"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](../../medusa/types/medusa.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<boolean>","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](fulfillment.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":false,"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":"fulfillmentData","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment being canceled","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"The method isn't expected to return any specific data.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<number>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="calculatePrice"/>
|
||||
|
||||
### createFulfillment
|
||||
|
||||
@@ -205,11 +253,38 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[ShippingMethodData](../../medusa/types/medusa.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](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.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":"fulfilled_quantity","type":"`null` \\| `number`","description":"The quantity of the Line Item that has been fulfilled.","optional":false,"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](../../entities/classes/entities.Order.mdx)","description":"The details of the order that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"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":"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":"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","expanLine truncated
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[ShippingMethodData](../../medusa/types/medusa.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](../../entities/classes/entities.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":"id","type":"`string`","description":"The line item's ID","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":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","optional":false,"defaultValue":"","expandable":false,"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":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The details of the cart that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"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":"order","type":"[Order](../../entities/classes/entities.Order.mdx)","description":"The details of the order that the line item may belongs 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":"swap","type":"[Swap](../../entities/classes/entities.Swap.mdx)","description":"The details of the swap 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":"claim_order","type":"[ClaimOrder](../../entities/classes/entities.ClaimOrder.mdx)","description":"The details of the claim that the line item may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"tax_lines","type":"[LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx)[]","description":"The details of the item's tax lines.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"adjustments","type":"[LineItemAdjustment](../../entities/classes/entities.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":"title","type":"`string`","description":"The title of the Line Item.","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":"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":"is_return","type":"`boolean`","description":"Is the item being returned","optional":false,"defaultValue":"false","expandable":false,"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":"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":"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":"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":"unit_price","type":"`number`","description":"The price of one unit of the content in the Line Item. This should be in the currencLine truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)>","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":[]}]}]} sectionTitle="createFulfillment"/>
|
||||
|
||||
### 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":"fulfillmentData","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment being canceled","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="cancelFulfillment"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","optional":false,"defaultValue":"","description":"The method isn't expected to return any specific data.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="cancelFulfillment"/>
|
||||
|
||||
### createReturn
|
||||
|
||||
@@ -235,11 +310,11 @@ class MyFulfillmentService extends AbstractFulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"returnOrder","type":"[CreateReturnType](../../medusa/types/medusa.CreateReturnType.mdx)","description":"the return that the fulfillment is being created for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"returnOrder","type":"[CreateReturnType](../../medusa/types/medusa.CreateReturnType.mdx)","description":"the return that the fulfillment is being created for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createReturn"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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":[]}]}]} sectionTitle="createReturn"/>
|
||||
|
||||
### getFulfillmentDocuments
|
||||
|
||||
@@ -262,38 +337,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment that you're retrieving the documents for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"data","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` attribute of the fulfillment that you're retrieving the documents for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"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<any[]>","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":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getFulfillmentDocuments"/>
|
||||
|
||||
### getReturnDocuments
|
||||
|
||||
@@ -316,11 +364,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### 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":[]}]} />
|
||||
<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":[]}]} sectionTitle="getReturnDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getReturnDocuments"/>
|
||||
|
||||
### getShipmentDocuments
|
||||
|
||||
@@ -343,11 +391,11 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### 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":[]}]} />
|
||||
<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":[]}]} sectionTitle="getShipmentDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="getShipmentDocuments"/>
|
||||
|
||||
### retrieveDocuments
|
||||
|
||||
@@ -372,94 +420,46 @@ class MyFulfillmentService extends FulfillmentService {
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"fulfillmentData","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","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":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"fulfillmentData","type":"[FulfillmentProviderData](../../medusa/types/medusa.FulfillmentProviderData.mdx)","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":[]}]} sectionTitle="retrieveDocuments"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
|
||||
### shouldRetryTransaction\_
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"err","type":"`Record<string, unknown>` \\| `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"boolean","type":"`boolean`","optional":false,"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](../../medusa/types/medusa.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](../../medusa/types/medusa.FulfillmentProviderData.mdx)","description":"The `data` object passed in the body of the request.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The customer's cart details. It may be empty if the shipping method isn't associated with a cart, such as when it's associated with a claim.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"billing_address","type":"[Address](../../entities/classes/entities.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](../../entities/classes/entities.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":"discounts","type":"[Discount](../../entities/classes/entities.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_cards","type":"[GiftCard](../../entities/classes/entities.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":"items","type":"[LineItem](../../entities/classes/entities.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](../../entities/classes/entities.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](../../entities/classes/entities.PaymentSession.mdx)","description":"The details of the selected payment session in the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"payment_sessions","type":"[PaymentSession](../../entities/classes/entities.PaymentSession.mdx)[]","description":"The details of all payment sessions created on the cart.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The Line truncated
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Record<string, unknown>>","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](fulfillment.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](../../medusa/types/medusa.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<boolean>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} />
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<any>","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":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="retrieveDocuments"/>
|
||||
|
||||
### withTransaction
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"transactionManager","type":"`EntityManager`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"transactionManager","type":"`EntityManager`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} />
|
||||
<ParameterTypes parameters={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
|
||||
|
||||
### shouldRetryTransaction\_
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"err","type":"`Record<string, unknown>` \\| `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
|
||||
|
||||
### atomicPhase\_
|
||||
|
||||
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.
|
||||
|
||||
#### Type Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"TResult","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"TError","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"work","type":"(`transactionManager`: `EntityManager`) => Promise<TResult>","description":"the transactional work to be done","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationOrErrorHandler","type":"`IsolationLevel` \\| (`error`: TError) => Promise<void \\| TResult>","description":"the isolation level to be used for the work.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"maybeErrorHandlerOrDontFail","type":"(`error`: TError) => Promise<void \\| TResult>","description":"Potential error handler","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<TResult>","optional":false,"defaultValue":"","description":"the result of the transactional work","expandable":false,"children":[{"name":"TResult","type":"TResult","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} sectionTitle="atomicPhase_"/>
|
||||
Reference in new issue
Block a user