# Purchase links

Source: https://developers.swell.is/backend-api/purchase-links

Purchase links allow you to configure a pre-selected group of products within a cart and direct a customer to its checkout through a designated URL. Once enabled, the URL will be active and will direct anyone who clicks the link to an instance of the checkout, pre-populated with the products associated with that link.

## The purchase links model

### Fields

- `id` (string, auto): The unique identifier for the purchase link. Default: `{"$formula":"alphanum(8)"}`.
- `name` (string, required): Human-friendly name of the purchase link.
- `active` (boolean, auto): The active status of the purchase link is automatically set to off and must be toggled on to activate, share, and use. Default: `false`.
- `coupon` (Coupon): Expandable link to the coupon applied to purchase link items.
- `coupon_id` (objectId): ID of the coupon applied to purchase link items.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
- `date_created` (date, auto): Date the purchase link was created.
- `date_updated` (date, auto): Date the purchase link was last updated.
- `discount_total` (currency): Total discount amount.
- `discounts` (array of object): Discounts applied to purchase link items.
  - `id` (string): Unique identifier for the object.
  - `type` (string): Type of discount. Can be `coupon` or `promo-<id>` referring to the source of the discount. Custom discounts don't require this value.
  - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value.
  - `amount` (currency): Fixed discount amount.
  - `source_id` (objectId)
- `grand_total` (currency, auto): Grand total including items, shipping, and taxes.
- `item_discount` (currency): Total discount applied to line items.
- `items` (array of object): List of line items describing the products ordered.
  - `id` (objectId, auto): Unique identifier for the item.
  - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`.
  - `purchase_option` (object): Configuration of one or more purchase options for purchase link items. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
    - `type` (enum): Possible values: `standard`, `subscription`, `trial`.
    - `plan_id` (objectId): ID of the subscription plan.
  - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`.
    - `id` (objectId): Unique identifier for the object.
    - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`.
    - `product_id` (objectId, required): ID of the bundle item product.
    - `product` (product): Expandable link to the bundle item product.
    - `variant_id` (objectId): ID of the bundle item variant.
    - `variant` (variant): Expandable link to the bundle item variant.
    - `options` (array of object)
      - `id` (string): Unique identifier for the object.
      - `value` (string): Name value of the product option. When adding to the cart, specify either the product option value `id` or `name` (case-insensitive) to identify the value.
    - `amount_ratio` (float)
    - `price` (currency)
    - `discount_each` (currency)
    - `tax_each` (currency)
  - `product_id` (objectId): ID of product in the purchase link.
  - `product` (product): Expandable link to the product within the purchase link.
  - `variant_id` (objectId): ID of the product variant, if applicable.
  - `variant` (variant): Expandable link to the product variant.
  - `discount_total` (currency): Total discount applied to the item.
  - `discount_each` (currency): Total discount amount divided by quantity.
  - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See  [Storefront API](https://developers.swell.is/frontend-api/introduction) for details.
- `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Frontend API](https://developers.swell.is/frontend-api/introduction) for more details.
- `promotion_ids` (array of child_scalar): Array of promotion ids associated to the purchase link.
- `promotions` (Promotion): Link to promotions associated to the purchase link.
- `sub_total` (currency): The subtotal of all of the items in a purchase link.

### Example response

```json
{
  "active": true,
  "name": "Mythic Dawn Commentaries Collection",
  "items": [
    {
      "product_id": "628ba6011869c10019b41f70",
      "quantity": 1,
      "price": 60,
      "id": "628ba7241869c10019b41f7d",
      "orig_price": 60,
      "delivery": "shipment",
      "shipment_weight": 0,
      "price_total": 60,
      "discount_total": 0,
      "discount_each": 0
    },
    {
      "product_id": "628ba67a1869c10019b41f76",
      "quantity": 1,
      "price": 60,
      "id": "628ba728499bba0019b1a9c2",
      "orig_price": 60,
      "delivery": "shipment",
      "shipment_weight": 0,
      "price_total": 60,
      "discount_total": 0,
      "discount_each": 0
    },
    {
      "product_id": "628ba6b7499bba0019b1a9b2",
      "quantity": 1,
      "price": 60,
      "id": "628ba72b499bba0019b1a9c5",
      "orig_price": 60,
      "delivery": "shipment",
      "shipment_weight": 0,
      "price_total": 60,
      "discount_total": 0,
      "discount_each": 0
    },
    {
      "product_id": "628ba701499bba0019b1a9bb",
      "quantity": 1,
      "price": 60,
      "id": "628ba72d499bba0019b1a9c8",
      "orig_price": 60,
      "delivery": "shipment",
      "shipment_weight": 0,
      "price_total": 60,
      "discount_total": 0,
      "discount_each": 0
    }
  ],
  "shipment_delivery": true,
  "currency": "USD",
  "sub_total": 240,
  "item_discount": 0,
  "discount_total": 0,
  "grand_total": 240,
  "date_created": "2022-05-23T15:24:20.977Z",
  "date_updated": "2022-05-23T15:24:32.137Z",
  "id": "5wFVZQzV"
}
```


## Create a purchase link

Create a purchase link.

### Arguments

- `name` (string, required): Human-friendly name of the purchase link.
- `items` (array of object): List of line items describing the products ordered.
  - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`.
    - `id` (objectId): ID of the bundle item product.
    - `product_id` (objectId, required): ID of the bundle item product.
    - `product` (product): Expandable link to the bundle product.
    - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`.
    - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable.
    - `variant_id` (objectId): ID of the bundle item variant.
    - `variant` (variant): Expandable link to the bundle variant.
  - `description` (string): Description used for custom line items, when product is not defined.
  - `discounts` (array of object): List of discounts to apply to the item. Normally populated by applying a [coupon ](https://developers.swell.is/backend-api/coupons/the-coupon-model)or [promotions.](https://developers.swell.is/backend-api/promotions/the-promotion-model)
    - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `discounts` object.
    - `amount` (currency, required): Fixed discount amount.
  - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details.
  - `options` (array of object): Item options matching one or more of `product.options`. When adding to the cart, specify either option `id` or `name` (case-insensitive) to identify the option.

    Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID `send_email` and value as the recipient email address, and `send_note` as a custom message from the customer to the recipient sent by email.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the product option. Populated automatically when adding an option by ID.
    - `price` (currency): Additional price added onto the base price of the product.
    - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product.
    - `value` (string): Name value of the product option. When adding to the cart, specify either the product option value `id` or `name` (case-insensitive) to identify the value.
    - `variant` (boolean): Indicates the option refers to a variant aspect.
  - `delivery` (enum): Method of delivery taken automatically from `product.delivery` Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`.
  - `price` (currency): Price of the item. Override this value to set a custom price. Defaults to product price or sale price. Default: `{"$formula":"if(product_id, product.price)"}`.
  - `product_id` (objectId): ID of the item product.
  - `product` (product): Expandable link to the product, if applicable.
  - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`.
  - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable.
  - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings.
    - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `taxes` object.
    - `amount` (currency, required): Fixed tax amount.
  - `variant_id` (objectId): ID of the item variant, if applicable.
  - `variant` (variant): Expandable link to the variant, if applicable.
- `active` (boolean): Indicates the cart has been updated by a customer within the last 3 hours. Default: `true`.

### Example request

`POST /purchaselinks`

**cURL**

```sh
$ curl https://api.swell.store/purchaselinks \
  -u store-id:secret-key \
	-d name="Purchase link example" \
  -d active=true \
  -d items[0][product_id]=626034d4e7b741001968292d \
  -d items[0][quantity]=1 \
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/purchaselinks', {
	name: 'Purchase link example',
	active: true,
	items: [
    {
      product_id: '626034d4e7b741001968292d',
      quantity: 1,
    }
  ],
  });
```

**PHP**

```javascript
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/purchaselinks', [
  'name' => 'Purchase link example',
	'active' => 'true',
	'items' => [
    [
      'product_id' => '626034d4e7b741001968292d',
      'quantity' => 1,
    ]
]);
```

### Example response

```json
{
  "active": true,
  "name": "Purchase link example",
  "items": [
    {
      "product_id": "626034d4e7b741001968292d",
      "quantity": 1,
      "price": 5,
      "price_total": 5,
      "discount_total": 0,
      "discount_each": 0,
      "id": "62681502ea4c3f00138da5ea"
    }
  ],
  "currency": "USD",
  "sub_total": 5,
  "item_discount": 0,
  "discount_total": 0,
  "grand_total": 5,
  "date_created": "2022-04-26T15:51:30.324Z",
  "date_updated": "2022-04-26T15:52:33.949Z",
  "id": "DEEFRebs"
}
```


## Retrieve a purchase link

Retrieve a purchase link.

### Arguments

- `id` (objectId, required): The id of the cart to retrieve.

### Example request

`GET /purchaselinks`

**cURL**

```sh
$ curl https://api.swell.store/purchaselinks/{id} \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/purchaselinks/{id}');
```

**PHP**

```javascript
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/purchaselinks/{id}');
```

### Example response

```json
{
  "active": true,
  "name": "Purchase link example",
  "items": [
    {
      "product_id": "626034d4e7b741001968292d",
      "quantity": 1,
      "price": 5,
      "price_total": 5,
      "discount_total": 0,
      "discount_each": 0,
      "id": "62681502ea4c3f00138da5ea"
    }
  ],
  "currency": "USD",
  "sub_total": 5,
  "item_discount": 0,
  "discount_total": 0,
  "grand_total": 5,
  "date_created": "2022-04-26T15:51:30.324Z",
  "date_updated": "2022-04-26T15:52:33.949Z",
  "id": "DEEFRebs"
}
```


## Update a purchase link

Update a purchase link.

### Arguments

- `id` (objectId, required): Unique identifier for the cart.
- `name` (objectId): Human-friendly name of the purchase link.
- `active` (boolean): The active status of the purchase link is automatically set to off and must be toggled on to activate, share, and use. Default: `False`.
- `items` (array of object): List of line items describing the products ordered.
  - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`.
    - `id` (objectId): ID of the bundle item product.
    - `product_id` (objectId, required): ID of the bundle item product.
    - `product` (product): Expandable link to the bundle product.
    - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`.
    - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable.
    - `variant_id` (objectId): ID of the bundle item variant.
    - `variant` (variant): Expandable link to the bundle variant.
  - `description` (string): Description used for custom line items, when product is not defined.
  - `discounts` (array of object): List of discounts to apply to the item. Normally populated by applying a [coupon ](https://developers.swell.is/backend-api/coupons/the-coupon-model)or [promotions.](https://developers.swell.is/backend-api/promotions/the-promotion-model)
    - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `discounts` object.
    - `amount` (currency, required): Fixed discount amount.
  - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details.
  - `options` (array of object): Item options matching one or more of `product.options`. When adding to the cart, specify either option `id` or `name` (case-insensitive) to identify the option.

    Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID `send_email` and value as the recipient email address, and `send_note` as a custom message from the customer to the recipient sent by email.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the product option. Populated automatically when adding an option by ID.
    - `price` (currency): Additional price added onto the base price of the product.
    - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product.
    - `value` (string): Name value of the product option. When adding to the cart, specify either the product option value `id` or `name` (case-insensitive) to identify the value.
    - `variant` (boolean): Indicates the option refers to a variant aspect.
  - `delivery` (enum): Method of delivery taken automatically from `product.delivery` Possible values: `shipment`, `giftcard`, `subscription`. Default: `{"$formula":"if(product_id, product.delivery)"}`.
  - `price` (currency): Price of the item. Override this value to set a custom price. Defaults to product price or sale price. Default: `{"$formula":"if(product_id, product.price)"}`.
  - `product_id` (objectId): ID of the item product.
  - `product` (product): Expandable link to the product, if applicable.
  - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`.
  - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable.
  - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings.
    - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the cart `taxes` object.
    - `amount` (currency, required): Fixed tax amount.
  - `variant_id` (objectId): ID of the item variant, if applicable.
  - `variant` (variant): Expandable link to the variant, if applicable.
- `coupon_code` (string): Coupon code applied to the cart. See [coupons](https://developers.swell.is/backend-api/coupons) for details.
- `promotion_ids` (array of child_scalar): List of promotion IDs applied to the cart.

### Example request

`PUT /purchaselinks/:id`

**cURL**

```sh
$ curl https://api.swell.store/purchaselinks/DEEFRebs \
  -u store-id:secret-key \
  -d active=true \
  -X PUT
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/purchaselinks/{id}', {
  id: 'DEEFRebs',
  active: true
});
```

**PHP**

```javascript
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/purchaselinks/{id}', [
  'id' => 'DEEFRebs',
  'active' => true
]);
```

### Example response

```json
{
  "active": true,
  "name": "Purchase link example",
  "items": [
    {
      "product_id": "626034d4e7b741001968292d",
      "quantity": 1,
      "price": 5,
      "price_total": 5,
      "discount_total": 0,
      "discount_each": 0,
      "id": "62681502ea4c3f00138da5ea"
    }
  ],
  "currency": "USD",
  "sub_total": 5,
  "item_discount": 0,
  "discount_total": 0,
  "grand_total": 5,
  "date_created": "2022-04-26T15:51:30.324Z",
  "date_updated": "2022-04-26T15:52:33.949Z",
  "id": "DEEFRebs"
}
```


## List all purchase links

List all purchase links.

### Arguments

- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /purchaselinks`

**cURL**

```sh
$ curl https://api.swell.store/purchaselinks/ \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/purchaselinks/');
```

**PHP**

```javascript
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/purchaselinks/');
```

### Example response

```json
{
  "count": 39,
  "results": [
    {
      "active": true,
      "name": "Purchase link example",
      "items": [
        {
          "product_id": "626034d4e7b741001968292d",
          "options": [
            {
              "id": "626034de60bd1a69a444f233",
              "name": "Size20-04",
              "value": "s",
              "value_id": "626034ee60bd1a69a444f234",
              "variant": true
            }
          ],
          "quantity": 1,
          "price": 5,
          "price_total": 5,
          "discount_total": 0,
          "discount_each": 0,
          "id": "62681502ea4c3f00138da5ea"
        }
      ],
      "currency": "USD",
      "sub_total": 5,
      "item_discount": 0,
      "discount_total": 0,
      "grand_total": 5,
      "date_created": "2022-04-26T15:51:30.324Z",
      "date_updated": "2022-04-26T15:52:33.949Z",
      "id": "DEEFRebs"
    },
    {
      "active": true,
      "name": "Test items",
      "items": [
        {
          "product_id": "625daa41e6e0e30019c4a084",
          "quantity": 1,
          "price": 100,
          "id": "625daa53e6e0e30019c4a2a3",
          "orig_price": 100,
          "delivery": "shipment",
          "shipment_weight": 0,
          "price_total": 100,
          "discount_total": 50,
          "discount_each": 50,
          "discounts": [
            {
              "id": "coupon-0",
              "amount": 50
            }
          ]
        }
      ],
      "shipment_delivery": true,
      "currency": "USD",
      "sub_total": 100,
      "item_discount": 50,
      "discount_total": 50,
      "grand_total": 50,
      "date_created": "2022-04-18T17:51:34.937Z",
      "date_updated": "2022-04-18T18:13:40.581Z",
      "coupon_code": "SIMPLETEST",
      "promotion_ids": [
        null,
        null,
        null,
        null,
        null,
        null,
        null,
        "625da6a2e6e0e30019c471dd"
      ],
      "coupon_id": "625da691e6e0e30019c46fea",
      "discounts": [
        {
          "type": "coupon",
          "rule": {
            "value_fixed": 50,
            "type": "total",
            "value_type": "fixed"
          },
          "amount": 50,
          "id": "coupon-0"
        }
      ],
      "shipment_discount": null,
      "id": "vASbh0zY"
    },
    {
      "name": "NEW PURCHASE LINK",
      "items": [
        {
          "purchase_option": {
            "plan_id": "6256eb710c7aaf0012dd1731",
            "billing_schedule": {
              "interval": "weekly",
              "interval_count": 1,
              "trial_days": 0,
              "limit": null
            },
            "type": "subscription",
            "plan_name": "Weekly"
          },
          "quantity": 1,
          "price": 65,
          "product_id": "6256eb710c7aaf0012dd1722",
          "id": "62599ad09a57a6001a8ca827",
          "orig_price": 65,
          "shipment_weight": 0,
          "price_total": 65,
          "discount_total": 0,
          "discount_each": 0
        }
      ],
      "subscription_delivery": true,
      "currency": "USD",
      "sub_total": 65,
      "item_discount": 0,
      "discount_total": 0,
      "grand_total": 65,
      "date_created": "2022-04-15T16:18:24.644Z",
      "active": true,
      "date_updated": "2022-04-15T16:31:35.254Z",
      "id": "midpIahm"
    },
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 15,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    },
    "2": {
      "start": 16,
      "end": 30
    },
    "3": {
      "start": 31,
      "end": 39
    }
  }
}
```


## Delete a purchase link

Delete a purchase link.

### Arguments

- `id` (objectId, required): The id for the purchase link to delete.

### Example request

`DELETE /purchaselinks`

**cURL**

```sh
$ curl https://api.swell.store/purchaselinks/{id} \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.delete('/purchaselinks/{id}', {
});
```

**PHP**

```javascript
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/purchaselinks/{id}', [
]);
```

### Example response

```json
{
  "active": true,
  "name": "Purchase link example",
  "items": [
    {
      "product_id": "626034d4e7b741001968292d",
      "quantity": 1,
      "price": 5,
      "price_total": 5,
      "discount_total": 0,
      "discount_each": 0,
      "id": "62681502ea4c3f00138da5ea"
    }
  ],
  "currency": "USD",
  "sub_total": 5,
  "item_discount": 0,
  "discount_total": 0,
  "grand_total": 5,
  "date_created": "2022-04-26T15:51:30.324Z",
  "date_updated": "2022-04-26T15:52:33.949Z",
  "id": "DEEFRebs"
}
```