---
title: "Create a purchase"
method: POST
path: "/api/business/{businessId}/branch/{branchId}/purchase"
tags: ["Purchase"]
---

# Create a purchase

`POST /api/business/{businessId}/branch/{branchId}/purchase`

Create and return a purchase for the specified business id and branch id. Purchase can be for various items including appointments, products, courses and vouchers. 
            <br/>One thing to note is the rounding strategy employed when applying taxes and discounts. Tax and discounts are always rounded HALF UP up to the cent. This applies to all currencies. For example: 
            <br/>With VAT of 20% on $100 the tax is $16.6666... which is rounded to $16.67. 
            With a sales tax of 10.5% on $1 we get $0.105 which is rounded to $0.11. 10.4% would be rounded to $0.10.
            <br/>For salons where the price of goods / services are inclusive of tax, you should provide the gross amount as price for each purchase item. For example: 
            <br/>A purchase item whose net price is €100 with tax at 20%, should have its gross price of €120 specified as the item price in the request.
            <br/>For salons where the price of goods / services are exclusive of tax, you should provide the net amount as price for each purchase item. For example: 
            <br/>A purchase item whose net price is $100 with tax at 20%, should have its net price of $100 specified as the item price in the request. However, the total payment amount for the sale must be the gross amount. In this example, where a single item with a net price of $100 is purchased at a 20% tax rate, the total payment amount for the sale is $120.
            <br/><h2>Payment</h2>
            <p>
            If the request contains a larger payment amount than is needed to cover the total cost of items being purchased, we return the difference as change. Please note that overpayment is determined based on the tax rates currently assigned in Phorest to the items being purchased, and not on the tax rates specified in the API request.
            <br/>If the request contains a smaller payment amount than is needed to cover the total cost of items being purchased, we reject the purchase and return an error. Please note that underpayment is determined based on the tax rates currently assigned in Phorest to the items being purchased, and not on the tax rates specified in the API request.
            </p>
            <br/><h2>Credit Account Transaction</h2>
            <p>
            A purchase of for clients credit account transaction needs outstandingBalancePayment set to true.  With this request you'll also need a staffId and price.
            </p>
            <br/><h2>Voucher</h2>
            <p>
            System supports creating vouchers sales via <code>purchase</code> operation. If purchase item contains voucher data, it will be treated as a voucher purchase item. <br/>
            In that case, following rules will apply: 
                <ul>
                    <li>
                        <code>serial</code> <br/>
                        If voucher's serial number is not provided, system will generate it
                    </li>
                    <li>
                        <code>expiry date</code> <br/>
                        Expiry date must be in future.
                    </li>
                    <li>
                        <code>quantity</code> <br/>
                        Number of vouchers to be created depends on the <code>quantity</code> field.
                        Example: For <code>quantity=2</code> and <code>price=1.00</code>, System will generate 2 vouchers with balance 1.00.
                    </li>
                    <li>
                        <code>tax-voucher</code> <br/>
                        On the voucher sale, tax won't be calculated so the tax field is not required.
                    </li>
                </ul>
            </p>

## Path parameters

- `businessId` string, required
- `branchId` string, required

## Request body

- CreatePurchaseRequest
  - `number` string, required — Must be unique across all purchases
  - `clientId` string, required — The client making the purchase
  - `payments` Payment[] — The payment method(s) used to make the purchase. Only a single payment method is supported currently
    - `type` 'CASH' | 'CREDIT' | 'DEBIT' | 'OTHER', required — Can be one of CASH, CREDIT, DEBIT, OTHER. If OTHER is specified, it indicates a custom payment type was used and therefore it must be accompanied by the id of the custom payment type in the customPaymentTypeId field.
    - `amount` number, required — The total payment amount.
    - `customPaymentTypeId` string — The id of the custom payment type. Only required if type is 'OTHER'
  - `items` Item[] — The items being purchased
    - `description` string — A description of the course.
    - `price` number, required — The price of the course or voucher.
    - `courseId` string — The id of the course being purchased
    - `staffId` string — The id of the staff member associated with the purchase
    - `outstandingBalancePayment` boolean — Set to true to create a client credit account transaction
    - `quantity` number — The quantity to be purchased
    - `appointmentId` string — The id of the appointment that is to be paid
    - `branchProductId` string — The id of a product that is to be paid
    - `taxRates` TaxRateResponse[] — The tax rates associated with the purchase
      - `taxId` string — Unique id for the taxRate
      - `name` string — The customTypeName given to the tax rate.
      - `rate` number — The total tax amount.
      - `type` 'SERVICE' | 'PRODUCT' — The type of item this tax applies to. Can be either SERVICE or PRODUCT
    - `voucher` VoucherPurchase — The voucher purchase item
      - `expiryDate` string, date-time — Expiration date of a voucher.
      - `serialNumber` string — Unique id for the voucher. If not provided, system will generate voucher serial number
      - `voucherRef` string, uri

## Response `201`

Purchase created successfully

- ErrorResponse
  - `statusCode` integer
  - `id` string
  - `detail` string
  - `errorCode` string

## Other responses

- `400` — Bad Request
- `404` — Business or branch with the specified ids don't exist
- `429` — Request rate limit exceeded. Current limit set to 100 rps.
- `500` — Internal Server Error

---

[API](https://skmtc.net/phorest/apis/third-party-api.md) · [All operations](https://skmtc.net/phorest/apis/third-party-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phorest/third-party-api/revisions/2218bc90d39c/schema)