> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manifestfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchases

# Overview

The Purchase object represents a one-time payment of money from a Buyer to your organization.

***

# Methods

<Tabs>
  <Tab title="Create">
    <Card icon="square-plus" iconType="solid" color="#86B74B">
      **`POST`  /purchase**<br />
      Create a new purchase.
    </Card>

    ## Body Parameters

    <ParamField body="buyer" type="string" required="true">
      ID of buyer making the purchase.
    </ParamField>

    <ParamField body="items" type="array" required="true">
      Array of items in the purchase, each containing a `name`, `description`, `amount_in_cents`, and `quantity` info.

      <Expandable title="Object">
        <ParamField body="name" type="string" required="true">
          Item name
        </ParamField>

        <ParamField body="description" type="string">
          Additional details
        </ParamField>

        <ParamField body="amount_in_cents" type="integer" required="true">
          Item price (negative values treated as discounts)
        </ParamField>

        <ParamField body="quantity" type="integer" default={1}>
          Number of items purchased
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="auto_refund_on_fraud" type="boolean" default={false}>
      If `true`, the purchase is eligible to be automatically refunded if a later fraud alert is detected on the payment card, minimizing the risk of chargebacks. A common use case is to set this to `true` if you are selling digital goods. Contact Manifest to configure your fraud refund window (default is 72 hours).

      The Purchase status will be updated to `refunded` and you will receive a `purchase.update` webhook after the refund is processed.
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data)
      page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // POST /purchase
      {
          "buyer": "buy_XXXXX",
          "items": [{
              "name": "Triangle Logo Tee",
              "description": "XL",
              "amount_in_cents": 3000,
              "quantity": 2
          }]
      }
      ```

      ```json Response theme={null}
      {
          "id": "pch_YYYYY",
          "buyer": "buy_XXXXX",
          "status": "created",
          "items": [{
              "name": "Triangle Logo Tee",
              "description": "XL",
              "amount_in_cents": 3000,
              "quantity": 2
          }],
          "total_in_cents": 6000,
          "auto_refund_on_fraud": false,
          "user_data": {},
          "created_at": "2025-01-02T21:18:16.704Z",
          "updated_at": "2025-01-02T21:18:16.704Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Commit">
    <Card icon="square-star" iconType="solid" color="#86B74B">
      **`POST`  /purchase/:id/commit**<br />
      Execute purchase. Throws an error if the purchase is not in the `created` state. Include an [**idempotency key**](/reference/idempotency) header to make the request idempotent.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the purchase to execute.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      // POST /purchase/pch_YYYYY/commit
      {
          "id": "pch_YYYYY",
          "buyer": "buy_XXXXX",
          "status": "pending",
          "items": [{
              "name": "Triangle Logo Tee",
              "description": "XL",
              "amount_in_cents": 3000,
              "quantity": 2
          }],
          "total_in_cents": 6000,
          "auto_refund_on_fraud": false,
          "user_data": {},
          "created_at": "2025-01-02T21:18:16.704Z",
          "updated_at": "2025-01-02T21:18:16.704Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get">
    <Card icon="square-arrow-right" iconType="solid" color="#425BE0">
      **`GET`  /purchase/:id**<br />
      Get details of one of your purchases.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the purchase to retrieve.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "id": "pch_YYYYY",
          "buyer": "buy_XXXXX",
          "status": "created",
          "items": [{
              "name": "Triangle Logo Tee",
              "description": "XL",
              "amount_in_cents": 3000,
              "quantity": 2
          }],
          "total_in_cents": 6000,
          "auto_refund_on_fraud": false,
          "user_data": {},
          "created_at": "2025-01-02T21:18:16.704Z",
          "updated_at": "2025-01-02T21:18:16.704Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Update">
    <Card icon="square-pen" iconType="solid" color="#F1E067">
      **`PUT`  /purchase/:id**<br />
      Update data associated with one of your enterprise's purchases. Since a checkout page may be rendered anytime after purchase creation, we do not let you update purchase fields that might materially change the nature of transaction.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the purchase to update.
    </ParamField>

    ## Body Parameters

    <ParamField body="status" type="string">
      The status of the purchase. Status can only be updated to `canceled`, `completed`, or `refunded`.
    </ParamField>

    <ParamField body="auto_refund_on_fraud" type="boolean">
      If `true`, the purchase is eligible to be automatically refunded if a later fraud alert is detected on the payment card, minimizing the risk of chargebacks. A common use case is to set this to `true` if you are selling digital goods. Contact Manifest to configure your fraud refund window (default is 72 hours).

      The Purchase status will be updated to `refunded` and you will receive a `purchase.update` webhook after the refund is processed.
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data) page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // PUT /purchase/pch_XXXXX
      {
        "userdata": {
          "key": "value"
        }
      }
      ```

      ```json Response theme={null}
      {
          "id": "pch_YYYYY",
          "buyer": "buy_XXXXX",
          "status": "created",
          "items": [{
              "name": "Triangle Logo Tee",
              "description": "XL",
              "amount_in_cents": 3000,
              "quantity": 2
          }],
          "total_in_cents": 6000,
          "auto_refund_on_fraud": false,
          "userdata": {
            "key": "value"
          },
          "created_at": "2025-01-02T21:18:16.704Z",
          "updated_at": "2025-01-02T21:18:16.704Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="List">
    <Card icon="square-list" iconType="solid" color="#BDE1CD">
      **`GET`  /purchase**<br />
      List all purchases from your enterprise.
    </Card>

    ## Query Parameters

    <ParamField query="page" type="integer">
      The page number to return. Default is 1.
    </ParamField>

    <ParamField query="page_size" type="integer">
      The number of items to return per page. Default is 10.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "data": [
              {
                  "id": "pch_XXXXX",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
              {
                  "id": "pch_YYYYY",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
              {
                  "id": "pch_ZZZZZ",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
          ],
          "pagination": {
              "page": 1,
              "page_size": 10,
              "total": 3
          }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="List for Buyer">
    <Card icon="square-list" iconType="solid" color="#BDE1CD">
      **`GET`  /buyer/:id/purchase**<br />
      List all purchases from your enterprise for a specific buyer.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the buyer to list purchases for.
    </ParamField>

    ## Query Parameters

    <ParamField query="page" type="integer">
      The page number to return. Default is 1.
    </ParamField>

    <ParamField query="page_size" type="integer">
      The number of items to return per page. Default is 10.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "data": [
              {
                  "id": "pch_XXXXX",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
              {
                  "id": "pch_YYYYY",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
              {
                  "id": "pch_ZZZZZ",
                  "buyer": "buy_XXXXX",
                  "status": "pending",
                  "items": [{
                      "name": "Triangle Logo Tee",
                      "description": "XL",
                      "amount_in_cents": 3000,
                      "quantity": 2
                  }],
                  "total_in_cents": 6000,
                  "auto_refund_on_fraud": false,
                  "user_data": {},
                  "created_at": "2025-01-02T21:18:16.704Z",
                  "updated_at": "2025-01-02T21:18:16.704Z"
              },
          ],
          "pagination": {
              "page": 1,
              "page_size": 10,
              "total": 3
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

# Properties

<ParamField body="id" type="string">
  Identifier for this purchase.
</ParamField>

<ParamField body="buyer" type="string">
  ID of buyer making the purchase.
</ParamField>

<ParamField body="status" type="string">
  Status of purchase. One of:

  | Status      | Description                                                                                                                                                                                                                     |
  | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `created`   | Purchase has been created.                                                                                                                                                                                                      |
  | `pending`   | Payment was successful, and money is being collected from the buyer.                                                                                                                                                            |
  | `settling`  | Payment is being settled to your operating account.                                                                                                                                                                             |
  | `completed` | Purchase has finished processing, and payment has been received in your operating account.                                                                                                                                      |
  | `error`     | Purchase has encountered an error.                                                                                                                                                                                              |
  | `canceled`  | Purchase has been canceled.                                                                                                                                                                                                     |
  | `refunded`  | Purchase has been refunded, and will be updated to `reversed` once the refund has been processed. If your attempt to refund a purchase fails, the payment will not be able to be reversed without a chargeback being processed. |
  | `reversed`  | Purchase has been reversed. This can happen if a refund is issued, or a chargeback is processed.                                                                                                                                |
</ParamField>

<ParamField body="items" type="array">
  Array of items in the purchase, each containing a `description`, `amount_in_cents`, and `meta` data. You are responsible for adding `items` for tax and shipping, if applicable.

  <Expandable title="Object">
    <ParamField body="name" type="string" required="true">
      Item name
    </ParamField>

    <ParamField body="description" type="string">
      Additional details
    </ParamField>

    <ParamField body="amount_in_cents" type="integer" required="true">
      Item price (negative values treated as discounts)
    </ParamField>

    <ParamField body="quantity" type="integer" default={1}>
      Number of items purchased
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="total_in_cents" type="number">
  Total amount of the purchase in cents.
</ParamField>

<ParamField body="fee_in_cents" type="number">
  Fee amount of the purchase in cents.
</ParamField>

<ParamField body="net_total_in_cents" type="number">
  Net total amount of the purchase in cents. This amount will be deposited into your operating account.
</ParamField>

<ParamField body="receipt_pdf_url" type="string">
  URL to the receipt PDF for the purchase, once paid.
</ParamField>

<ParamField body="payment_card_brand" type="string">
  Brand of the payment card used for the purchase, if available.
</ParamField>

<ParamField body="payment_card_last_four" type="string">
  Last 4 digits of the payment card used for the purchase, if available.
</ParamField>

<ParamField body="activity" type="array">
  Array of activity log entries for the purchase, each containing an entry and date.
</ParamField>

<ParamField body="auto_refund_on_fraud" type="boolean" default={false}>
  If `true`, the purchase is eligible to be automatically refunded if a later fraud alert is detected on the payment card, minimizing the risk of chargebacks. A common use case is to set this to `true` if you are selling digital goods. Contact Manifest to configure your fraud refund window (default is 72 hours).

  The Purchase status will be updated to `refunded` and you will receive a `purchase.update` webhook after the refund is processed.
</ParamField>

<ParamField body="user_data" type="object">
  User defined data associated with the purchase.
</ParamField>

<ParamField body="created_at" type="string">
  Date and time when the purchase was created.
</ParamField>

<ParamField body="updated_at" type="string">
  Date and time when the purchase was last updated.
</ParamField>