Using the following steps you will be able to handle returning a sale via the API.

1. Initiating the return.

In order to initiate a return of a sale, you should make a PUT request to the /api/2.0/sales/:id/actions/return endpoint. The id here should be of an existing, closed sale.

For this example we’re using the following URL:

https://ppapi.vendhq.com/api/2.0/sales/b8ca3a65-0183-11e4-fbb5-39f7fce5e39b/actions/return

Which gives us the following response:

{
    "data": {
        "id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
        "outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
        "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
        "user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
        "customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
        "invoice_number": "1570",
        "receipt_number": "1570",
        "invoice_sequence": 1570,
        "receipt_sequence": 1570,
        "status": "SAVED",
        "note": "",
        "short_code": "ovvfkk",
        "return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
        "created_at": "2016-09-19T20:28:03+00:00",
        "total_price": -200,
        "total_loyalty": 0,
        "total_tax": -30,
        "updated_at": "2016-09-19T20:28:03+00:00",
        "sale_date": "2016-09-19T20:28:03+00:00",
        "deleted_at": null,
        "line_items": [
            {
                "id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
                "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                "quantity": -1,
                "price": 200,
                "unit_price": 200,
                "price_total": -200,
                "total_price": -200,
                "discount": 0,
                "unit_discount": 0,
                "discount_total": 0,
                "total_discount": 0,
                "loyalty_value": 23,
                "unit_loyalty_value": 23,
                "total_loyalty_value": -23,
                "cost": 100,
                "unit_cost": 100,
                "cost_total": -100,
                "total_cost": -100,
                "tax": 30,
                "unit_tax": 30,
                "tax_total": -30,
                "total_tax": -30,
                "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                "tax_components": [
                    {
                        "rate_id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
                        "total_tax": 30
                    }
                ],
                "price_set": true,
                "sequence": 1,
                "note": null,
                "status": "SAVED",
                "is_return": true
            },
            {
                "id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
                "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                "quantity": -1,
                "price": 0,
                "unit_price": 0,
                "price_total": 0,
                "total_price": 0,
                "discount": 0,
                "unit_discount": 0,
                "discount_total": 0,
                "total_discount": 0,
                "loyalty_value": 0,
                "unit_loyalty_value": 0,
                "total_loyalty_value": 0,
                "cost": 100,
                "unit_cost": 100,
                "cost_total": -100,
                "total_cost": -100,
                "tax": 0,
                "unit_tax": 0,
                "tax_total": 0,
                "total_tax": 0,
                "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                "tax_components": [
                    {
                        "rate_id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
                        "total_tax": 0
                    }
                ],
                "price_set": true,
                "sequence": 0,
                "note": null,
                "status": "SAVED",
                "is_return": true
            }
        ],
        "payments": [],
        "taxes": [],
        "version": 1978890425
    }
}

The most important part of that response is the id of the highest-level object, in this case 06bf537b-c783-11e6-f6b9-7ea7909ffedd. This is an id of a new parked (status = SAVED) sale that was just created in the account.

2. Getting the data

Now, using the good, old /api/register_sales/:id endpoint you should GET all the data for that sale. In our case, it will be a GET request to:

https://ppapi.vendhq.com/api/register_sales/06bf537b-c783-11e6-f6b9-7ea7909ffedd

Which gives us the following response:

{
    "register_sales": [
        {
            "id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
            "source": "USER",
            "source_id": "",
            "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
            "market_id": "1",
            "customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
            "customer_name": "",
            "customer": {
                "id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
                "name": "",
                "customer_code": "WALKIN",
                "customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
                "customer_group_name": "All Customers",
                "enable_loyalty": 0,
                "loyalty_balance": "0",
                "updated_at": "2014-08-01 00:14:49",
                "deleted_at": "",
                "balance": "0",
                "year_to_date": "0",
                "date_of_birth": "",
                "sex": "",
                "custom_field_1": "",
                "custom_field_2": "",
                "custom_field_3": "",
                "custom_field_4": "",
                "note": "",
                "contact": {}
            },
            "user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
            "user_name": "piotr.zurek@gmail.com",
            "sale_date": "2016-09-19 20:28:03",
            "created_at": "2016-09-19 20:28:03",
            "updated_at": "2016-09-19 20:28:03",
            "total_price": -200,
            "total_cost": -200,
            "total_tax": -30,
            "tax_name": "GST",
            "note": "",
            "status": "SAVED",
            "short_code": "ovvfkk",
            "invoice_number": "1570",
            "return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
            "register_sale_products": [
                {
                    "id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
                    "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                    "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
                    "sequence": "0",
                    "handle": "mofo",
                    "sku": "10006",
                    "name": "mofo",
                    "quantity": -1,
                    "price": 0,
                    "cost": 100,
                    "price_set": 1,
                    "discount": 0,
                    "loyalty_value": 0,
                    "tax": 0,
                    "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                    "tax_name": "GST",
                    "tax_rate": 0.15,
                    "tax_total": 0,
                    "price_total": 0,
                    "display_retail_price_tax_inclusive": "1",
                    "status": "SAVED",
                    "attributes": [
                        {
                            "name": "is_return",
                            "value": "1"
                        }
                    ]
                },
                {
                    "id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
                    "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                    "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
                    "sequence": "1",
                    "handle": "mofo",
                    "sku": "10006",
                    "name": "mofo",
                    "quantity": -1,
                    "price": 200,
                    "cost": 100,
                    "price_set": 1,
                    "discount": 0,
                    "loyalty_value": 23,
                    "tax": 30,
                    "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                    "tax_name": "GST",
                    "tax_rate": 0.15,
                    "tax_total": -30,
                    "price_total": -200,
                    "display_retail_price_tax_inclusive": "1",
                    "status": "SAVED",
                    "attributes": [
                        {
                            "name": "is_return",
                            "value": "1"
                        }
                    ]
                }
            ],
            "totals": {
                "total_tax": -30,
                "total_price": -200,
                "total_payment": 0,
                "total_to_pay": -230
            },
            "register_sale_payments": []
        }
    ]
}

3. Finalizing the return

If you look above you will notice 2 things about the return sale we’ve just created. Its status is SAVED and it has no payments on it. Changing those 2 things will be required to finalize the return. We’ll do that by POSTing a slightly modified payload from above back to the /api/register_sales endpoint. It’s important to note that there is no id included in the URL for this request: The changes are:

https://ppapi.vendhq.com/api/register_sales

The changes are:

"status": "CLOSED",

and

"register_sale_payments": [{
	"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
	"amount": -230
}]

The full payload will look like this:

{
	"id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
	"source": "USER",
	"source_id": "",
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"market_id": "1",
	"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
	"customer_name": "",
	"customer": {
		"id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
		"name": "",
		"customer_code": "WALKIN",
		"customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
		"customer_group_name": "All Customers",
		"enable_loyalty": 0,
		"loyalty_balance": "0",
		"updated_at": "2014-08-01 00:14:49",
		"deleted_at": "",
		"balance": "0",
		"year_to_date": "0",
		"date_of_birth": "",
		"sex": "",
		"custom_field_1": "",
		"custom_field_2": "",
		"custom_field_3": "",
		"custom_field_4": "",
		"note": "",
		"contact": {}
	},
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_name": "piotr.zurek@gmail.com",
	"sale_date": "2016-09-19 20:28:03",
	"created_at": "2016-09-19 20:28:03",
	"updated_at": "2016-09-19 20:28:03",
	"total_price": -200,
	"total_cost": -200,
	"total_tax": -30,
	"tax_name": "GST",
	"note": "",
	"status": "CLOSED",
	"short_code": "ovvfkk",
	"invoice_number": "1570",
	"return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
	"register_sale_products": [{
		"id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
		"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
		"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
		"sequence": "0",
		"handle": "mofo",
		"sku": "10006",
		"name": "mofo",
		"quantity": -1,
		"price": 0,
		"cost": 100,
		"price_set": 1,
		"discount": 0,
		"loyalty_value": 0,
		"tax": 0,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		"tax_name": "GST",
		"tax_rate": 0.15,
		"tax_total": 0,
		"price_total": 0,
		"display_retail_price_tax_inclusive": "1",
		"status": "SAVED",
		"attributes": [{
			"name": "is_return",
			"value": "1"
		}]
	}, {
		"id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
		"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
		"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
		"sequence": "1",
		"handle": "mofo",
		"sku": "10006",
		"name": "mofo",
		"quantity": -1,
		"price": 200,
		"cost": 100,
		"price_set": 1,
		"discount": 0,
		"loyalty_value": 23,
		"tax": 30,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		"tax_name": "GST",
		"tax_rate": 0.15,
		"tax_total": -30,
		"price_total": -200,
		"display_retail_price_tax_inclusive": "1",
		"status": "SAVED",
		"attributes": [{
			"name": "is_return",
			"value": "1"
		}]
	}],
	"totals": {
		"total_tax": -30,
		"total_price": -200,
		"total_payment": 0,
		"total_to_pay": -230
	},
	"register_sale_payments": [{
		"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
		"amount": -230
	}]
}

This should result in the following response:

{
    "register_sale": {
        "id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
        "source": "USER",
        "source_id": "",
        "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
        "market_id": "1",
        "customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
        "customer_name": " ",
        "customer": {
            "id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
            "name": " ",
            "customer_code": "WALKIN",
            "customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
            "customer_group_name": "All Customers",
            "first_name": "",
            "last_name": "",
            "company_name": "",
            "phone": "",
            "mobile": "",
            "fax": "",
            "email": "",
            "twitter": "",
            "website": "",
            "physical_address1": "",
            "physical_address2": "",
            "physical_suburb": "",
            "physical_city": "",
            "physical_postcode": "",
            "physical_state": "",
            "physical_country_id": "",
            "postal_address1": "",
            "postal_address2": "",
            "postal_suburb": "",
            "postal_city": "",
            "postal_postcode": "",
            "postal_state": "",
            "postal_country_id": "",
            "enable_loyalty": 0,
            "loyalty_balance": "0",
            "updated_at": "2014-08-01 00:14:49",
            "deleted_at": "",
            "balance": "0",
            "year_to_date": "0",
            "date_of_birth": "",
            "sex": "",
            "custom_field_1": "",
            "custom_field_2": "",
            "custom_field_3": "",
            "custom_field_4": "",
            "note": "",
            "contact": {
                "company_name": "",
                "phone": "",
                "email": ""
            }
        },
        "user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
        "user_name": "piotr.zurek@gmail.com",
        "sale_date": "2016-09-19 20:28:03",
        "created_at": "2016-09-19 20:28:03",
        "updated_at": "2016-09-19 20:56:39",
        "total_price": -200,
        "total_cost": -200,
        "total_tax": -30,
        "tax_name": "GST",
        "note": "",
        "status": "CLOSED",
        "short_code": "ovvfkk",
        "invoice_number": "1570",
        "return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
        "register_sale_products": [
            {
                "id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
                "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
                "sequence": "0",
                "handle": "mofo",
                "sku": "10006",
                "name": "mofo",
                "quantity": -1,
                "price": 200,
                "cost": 100,
                "price_set": 1,
                "discount": 0,
                "loyalty_value": 23,
                "tax": 30,
                "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                "tax_name": "GST",
                "tax_rate": 0.15,
                "tax_total": -30,
                "price_total": -200,
                "display_retail_price_tax_inclusive": "1",
                "status": "CONFIRMED",
                "attributes": [
                    {
                        "name": "is_return",
                        "value": "1"
                    }
                ]
            },
            {
                "id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
                "product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
                "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
                "sequence": "0",
                "handle": "mofo",
                "sku": "10006",
                "name": "mofo",
                "quantity": -1,
                "price": 0,
                "cost": 100,
                "price_set": 1,
                "discount": 0,
                "loyalty_value": 0,
                "tax": 0,
                "tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
                "tax_name": "GST",
                "tax_rate": 0.15,
                "tax_total": 0,
                "price_total": 0,
                "display_retail_price_tax_inclusive": "1",
                "status": "CONFIRMED",
                "attributes": [
                    {
                        "name": "is_return",
                        "value": "1"
                    }
                ]
            }
        ],
        "totals": {
            "total_tax": -30,
            "total_price": -200,
            "total_payment": -230,
            "total_to_pay": 0
        },
        "register_sale_payments": [
            {
                "id": "06bf537b-c783-11e6-f6b9-7eab8f8ed241",
                "payment_type_id": "1",
                "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
                "retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
                "name": "Cash",
                "label": "Cash",
                "payment_date": "2016-09-19T20:28:03Z",
                "amount": -230
            }
        ],
        "taxes": [
            {
                "id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
                "tax": -30,
                "name": "GST",
                "rate": 0.15
            }
        ]
    }
}

4. Final notes

  • By modifying the final payload, it is possible to only return certain products from a sale. If that is done, the “return” payment should be adjusted to just the value of the returned item.
  • It is possible to create multiple returns against a single sale.