Zoey REST API reference · Interactive version: apidocs.zoey.com
The Bill endpoint is available to Create an Invoice, Pay an Invoice, Get Invoice Details, Void an Invoice, Email Invoice PDF, Print Invoice PDF, or to Update an Invoice.
POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/attachments
Example request body:
{
"billId": 2809,
"attachments": [
{
"file_name": "attachment_1.jpg",
"file_mime_type": "image/png",
"file_content": "iVBORw0KGgo..."
}
]
}
DELETE https://container-url.zoeysite.com/api/rest/sales2/orders/bill/attachments
Example request body:
{
"billId": 2810,
"attachmentId": 29
}
POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill
This endpoint creates an Invoice.
It can also create a Shipment for the invoiced Items.
Required Top-Level Parameters
Each of the following five (5) Parameters must be included in the correct order to properly make this API call.
If you are not sending data for one of these five (5) parameters, it should be included in the call with null value.
{
"orderIncrementId": "100000024",
"itemsQty": { "106537": 15 },
"comment": null,
"shipmentData": null,
"extraData": { "send_email": 0, "due_date": "2023-09-19" }
}
ShipmentData
TrackingData
ExtraData
ExtraDataTotal
CommentConfig
Example request body:
{
"orderIncrementId": "100002958",
"itemsQty": {
"60012": "1"
},
"comment": "This is a comment that will show up in the order history",
"shipmentData": {
"send_email": "1",
"ship_immediately": true,
"tracking": [
{
"carrier_code": "usps",
"number": "987234987235",
"title": "United States Postal Service"
}
],
"attachments": [
{
"file_name": "attachment_2.png",
"file_mime_type": "image/png",
"file_content": "iVBORw0KGgo..."
}
]
},
"extraData": {
"send_email": "1",
"ignore_qty_multiplier": true,
"totals_info": [
{
"code": "shipping",
"base_raw_value": "101"
},
{
"code": "discount",
"base_raw_value": "102"
},
{
"code": "payment_surcharge",
"base_raw_value": "103"
},
{
"code": "tax",
"base_raw_value": "104"
}
],
"due_date": "2024-01-20 10:20:30",
"netterm": {
"term": "net10"
},
"comment": {
"is_visible_on_front": "1"
},
"attachments": [
{
"file_name": "attachment_2.png",
"file_mime_type": "image/png",
"file_content": "iVBORw0KGgo..."
}
]
}
}
Example response (Send), HTTP 200:
"7"
POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/pay
BillConfigData
Response
When amount is provided: the increment ID of the payment that was created.
When amount is not provided: the increment ID of the invoice that was created (unchanged).
PaymentCommentData
ShipmentData
TrackingData
Example request body:
{
"bill_id": "8377",
"data": {
"capture_case": "online",
"send_email": "1",
"shipmentData": {
"ship_items": {
"311": "1"
},
"tracking": [
{
"carrier_code": "usps",
"number": "987234987235",
"title": "United States Postal Service"
}
]
},
"comment_customer_notify": "1",
"comment_text": "This comment will be saved when paying the bill.",
"is_visible_on_front": "1"
}
}
Example response (Send), HTTP 200:
"100000259"
GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill?id=482
Query parameters:
| Name | Example | Notes |
|---|---|---|
id | 482 | ID of bill. (Optional if order_id is used) |
order_id | 796 | If used will get latest unpaid bill by order_id. (Optional if id is used) |
Example response (Get), HTTP 200:
{
"order_id": "678",
"store_id": "1",
"customer_id": "48",
"billing_address_id": "1351",
"shipping_address_id": "1352",
"global_currency_code": "USD",
"base_currency_code": "USD",
"store_currency_code": "USD",
"order_currency_code": "USD",
"store_to_base_rate": "1.0000",
"store_to_order_rate": "1.0000",
"base_to_global_rate": "1.0000",
"base_to_order_rate": "1.0000",
"discount_description": null,
"avatax_landed_cost_import_duties_amount": null,
"base_avatax_landed_cost_import_duties_amount": null,
"avatax_fixed_tax_amount": null,
"base_avatax_fixed_tax_amount": null,
"avatax_collected_taxes": null,
"total_qty": 4,
"bill": {
"id": "482",
"order_id": "678",
"invoice_id": null,
"increment_id": "100000434",
"replaced_increment_id": null,
"key": "665f7c62ab492211884440",
"state": "open",
"status": "open",
"can_edit": "0",
"is_paid": "0",
"payment_method": null,
"is_custom_payment_method": "0",
"allowed_payment_methods": null,
"is_void": "0",
"base_total": "220.0000",
"total": "220.0000",
"due_date": "2024-06-05 03:59:59",
"is_custom_due_date": "0",
"is_due_on_receipt": "1",
"config": {
"items": {
"54557": "1",
"54558": "1",
"54559": "1",
"54560": "1"
},
"create_invoice": "1",
"do_shipment": "0",
"send_email": "1",
"void_unpaid_bills": "0",
"comment_text": "",
"totals_info": [
{
"code": "subtotal",
"label": "Subtotal",
"raw_value": "4.00",
"base_raw_value": "4.00",
"value": "$4.0000",
"class": "total-md",
"include": "true",
"base_value": "",
"orig_base_raw_value": "4.00"
},
{
"code": "shipping",
"label": "Shipping",
"raw_value": "216.00",
"base_raw_value": "216.00",
"value": "$216.0000",
"class": "total-md",
"include": "true",
"base_value": "",
"orig_value": "",
... (truncated)
GET https://container-url.zoeysite.com/api/rest/sales2/orders/bills?order[order_id]=DESC&filters[created_at][from]=2024-01-01&filters[created_at][to]=2024-12-31
Query parameters:
| Name | Example | Notes |
|---|---|---|
limit | 2 | If used will get latest unpaid bill by order_id. (Optional if id is used) |
page | 1 | |
order[order_id] | DESC | |
filters[order_id] | 41 | |
filters[total_qty][gt] | 1 | |
filters[created_at][from] | 2024-01-01 | |
filters[created_at][to] | 2024-12-31 |
Example response (Get), HTTP 200:
{
"order_id": "678",
"store_id": "1",
"customer_id": "48",
"billing_address_id": "1351",
"shipping_address_id": "1352",
"global_currency_code": "USD",
"base_currency_code": "USD",
"store_currency_code": "USD",
"order_currency_code": "USD",
"store_to_base_rate": "1.0000",
"store_to_order_rate": "1.0000",
"base_to_global_rate": "1.0000",
"base_to_order_rate": "1.0000",
"discount_description": null,
"avatax_landed_cost_import_duties_amount": null,
"base_avatax_landed_cost_import_duties_amount": null,
"avatax_fixed_tax_amount": null,
"base_avatax_fixed_tax_amount": null,
"avatax_collected_taxes": null,
"total_qty": 4,
"bill": {
"id": "482",
"order_id": "678",
"invoice_id": null,
"increment_id": "100000434",
"replaced_increment_id": null,
"key": "665f7c62ab492211884440",
"state": "open",
"status": "open",
"can_edit": "0",
"is_paid": "0",
"payment_method": null,
"is_custom_payment_method": "0",
"allowed_payment_methods": null,
"is_void": "0",
"base_total": "220.0000",
"total": "220.0000",
"due_date": "2024-06-05 03:59:59",
"is_custom_due_date": "0",
"is_due_on_receipt": "1",
"config": {
"items": {
"54557": "1",
"54558": "1",
"54559": "1",
"54560": "1"
},
"create_invoice": "1",
"do_shipment": "0",
"send_email": "1",
"void_unpaid_bills": "0",
"comment_text": "",
"totals_info": [
{
"code": "subtotal",
"label": "Subtotal",
"raw_value": "4.00",
"base_raw_value": "4.00",
"value": "$4.0000",
"class": "total-md",
"include": "true",
"base_value": "",
"orig_base_raw_value": "4.00"
},
{
"code": "shipping",
"label": "Shipping",
"raw_value": "216.00",
"base_raw_value": "216.00",
"value": "$216.0000",
"class": "total-md",
"include": "true",
"base_value": "",
"orig_value": "",
... (truncated)
DELETE https://container-url.zoeysite.com/api/rest/sales2/orders/bill?id=8&order_id=26
Query parameters:
| Name | Example | Notes |
|---|---|---|
id | 8 | ID of bill. (Optional if order_id is used) |
order_id | 26 | If used will get latest unpaid bill by order_id. (Optional if id is used) |
GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/email?id=8
Query parameters:
| Name | Example | Notes |
|---|---|---|
id | 8 | Id of bill |
GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/print?id=8
Query parameters:
| Name | Example | Notes |
|---|---|---|
id | 8 | Id of Bill |
POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/update
Example request body:
{
"bill_id": "5664",
"data": {
"items": {
"8952": {
"qty": "2",
"base_price": "25.99"
},
"8953": {
"qty": "3",
"base_price": "19.99"
}
},
"totals_info": [
{
"code": "shipping",
"base_raw_value": "101"
},
{
"code": "discount",
"base_raw_value": "102"
},
{
"code": "payment_surcharge",
"base_raw_value": "103"
},
{
"code": "tax",
"base_raw_value": "104"
}
],
"due_date": "2024-01-20 10:20:30",
"netterm": {
"term": "net10"
},
"external_invoice_id": "EXT_INV_01"
}
}
GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/savedPayments?id={{bill_id}}
GET /sales2/orders/bill/savedPayments?id={{billId}}
Returns the saved cards and verified ACH bank accounts that can be used to pay an invoice. These belong to the account (company) that the invoice's order is on. Pass an id from this list as saved_payment to Pay Invoice (POST /sales2/orders/bill/pay) to charge it.
Invoicing must be enabled on the store, and the invoice's order must be on an account.
The API user's role needs the List Saved Payments For Invoice resource (sales/order/invoice/getBillSavedPayments).
200 OK: an array of saved payments. The array is empty if the account has no saved payments that can be charged.
Only payment methods that AutoPay supports are listed (Authorize.Net CIM, Stripe, Braintree, Stripe ACH). ACH accounts that haven't been verified yet are left out.
[
{
"id": "cim:11",
"type": "card",
"method": "cim",
"label": "Visa ending in 1111",
"brand": "Visa",
"last4": "1111",
"exp_month": "04",
"exp_year": "2029"
},
{
"id": "cryozonic_stripe:card_abc",
"type": "card",
"method": "cryozonic_stripe",
"label": "Office card",
"brand": "MasterCard",
"last4": "4444",
"exp_month": null,
"exp_year": null
},
{
"id": "cryozonic_achpayments:pm_bank_1",
"type": "ach",
"method": "cryozonic_achpayments",
"label": "Chase ending in 6789",
"brand": "Chase",
"last4": "6789",
"exp_month": null,
"exp_year": null
}
]
All errors return 400 Bad Request with a message.
Query parameters:
| Name | Example | Notes |
|---|---|---|
id | {{bill_id}} | The invoice (bill) ID. This is the same ID used by /sales2/orders/bill/print. |