Introduction

To use the Invoices API, import {invoices} from the wix-billing-backend module:

Copy
import { invoices } from "wix-billing-backend";
Did this help?

addPayment( )

Adds a payment to the invoice and reports the payment to the payment provider.

The addPayment() function returns a Promise that resolves when the specified payment is added to the invoice with the specified ID.

Method Declaration
Copy
function addPayment(id: IdAndVersion, payment: Payment): Promise<Response>;
Method Parameters
idIdAndVersionRequired

ID and version of the invoice.

paymentPaymentRequired

The payment that should be added to the invoice.

Returns
Return Type:Promise<Response>
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const addPayment = webMethod(
  Permissions.Anyone,
  (id, version, type, amount) => {
    const idAndVersion = {
      id: id,
      version: version,
    };

    const payment = {
      type: type,
      amount: amount,
      date: Date.now(),
    };

    return invoices.addPayment(idAndVersion, payment);
  },
);

/* Promise resolves to:
 * {
 *   {
 *     "id": {
 *       "id": "1ed3a515-24f9-4039-8937-2e69b6a2f33a",
 *       "version": 31
 *     }
 *   }
 * }
 */
Did this help?

createInvoice( )

Creates a new invoice.

The createInvoice() function returns a Promise that resolves to the created invoice's ID when the invoice is created.

Note: The customer ID and email address listed on the invoice must match an existing contact in the site's contact list.

Method Declaration
Copy
function createInvoice(invoiceFields: InvoiceFields): Promise<Response>;
Method Parameters
invoiceFieldsInvoiceFieldsRequired

The data used to create an invoice.

Returns
Return Type:Promise<Response>
Create a new invoice
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

const now = new Date();
const dueDate = new Date();
dueDate.setDate(now.getDate() + 30);

let customer = {
  // contact ID and email address must match an
  // existing contact in the site's contact list
  contactId: "4f7c6637-0657-4696-a00b-9bc2ae4e035d",
  email: "john.doe@somedomain.com",
  address: {
    city: "New York",
    subdivision: "NY",
    postalCode: "10011",
    country: "USA",
    addressLine: "235 W 23rd St",
  },
  billingAddress: {
    country: "USA",
    streetAddress: {
      value: "235 W 23rd St",
      type: "Name",
    },
    addressLine: "235 W 23rd St, New York, NY 10011, USA",
    addressLine2: "secondary address",
    postalCode: "10011",
    subdivision: "NY",
    city: "New York",
  },
  shippingAddress: {
    country: "USA",
    streetAddress: {
      value: "235 W 23rd St",
      type: "Name",
    },
    addressLine: "235 W 23rd St, New York, NY 10011, USA",
    addressLine2: "secondary address",
    postalCode: "10011",
    subdivision: "NY",
    city: "New York",
  },
  phone: "5555555555",
  company: "Some Company",
  companyId: "Some Company Id",
  fullName: "John Doe",
  firstName: "John",
  lastName: "Doe",
};

let lineItems = [
  {
    id: "00001",
    name: "Item 1",
    description: "First Item",
    price: 10.5,
    quantity: 3,
    taxes: [
      {
        name: "tax name",
        rate: 8.5,
        code: "tax code",
      },
    ],
  },
  {
    id: "00002",
    name: "Item 2",
    description: "Second Item",
    price: 50,
    quantity: 1,
    taxes: [
      {
        name: "tax name",
        rate: 8.5,
        code: "tax code",
      },
    ],
  },
];

let discount = {
  value: 2.5,
  type: "Fixed",
};

const payments = [
  {
    id: "00001",
    type: "Offline",
    amount: 25.5,
    date: now,
  },
];

let metadata = {
  notes: "Some note.",
  legalTerms: "Some legal terms",
  sourceUrl: "http://legalurl.com",
  source: "Some source",
  sourceRefId: "Some source ref id",
};

let dates = {
  issueDate: now,
  dueDate: dueDate,
};

export const createInvoice = webMethod(Permissions.Anyone, () => {
  let createInvoiceFields = {
    title: "My Invoice",
    customer: customer,
    currency: "USD",
    lineItems: lineItems,
    discount: discount,
    payments: payments,
    metadata: metadata,
    dates: dates,
    locale: {
      language: "ja",
    },
  };

  return invoices.createInvoice(createInvoiceFields);
});

/* Promise resolves to:
 * {
 *   "id": {
 *     "id": "fe00fd47-c30e-47da-9b5a-8cacfbed744d"
 *     "version": 23
 *   }
 * }
 */
Did this help?

createInvoicePreviewUrl( )

Creates a link that can be used by a customer to preview the invoice.

The createInvoicePreviewUrl() function returns a Promise that resolves to a temporary link to a preview of the invoice with the specified ID.

You can get a list of invoices by querying your site's "Billing/Invoices" collection. Each invoice in the query result contains the _id and version fields, which must be used when calling createInvoicePreviewUrl().

By default, createInvoicePreviewUrl() can be called by site contributors only. To allow customers to generate the invoice preview link, set suppressAuth in the options argument to true.

Method Declaration
Copy
function createInvoicePreviewUrl(
  id: IdAndVersion,
  options: AuthOptions,
): Promise<string>;
Method Parameters
idIdAndVersionRequired

Object containing the ID and version of the invoice.

optionsAuthOptions

An object with the following boolean property: suppressAuth.

Returns
Return Type:Promise<string>
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const myCreateInvoicePreviewUrlFunction = webMethod(
  Permissions.Anyone,
  async (myInvoiceId, myInvoiceVersion) => {
    const id = {
      id: myInvoiceId,
      version: myInvoiceVersion,
    };

    const options = {
      suppressAuth: false,
    };

    return await invoices.createInvoicePreviewUrl(id, options);
  },
);

/* Promise resolves to:
 *
 * "https://invoices.wix.com/invoice/4ffbe78f-d789-5f3b-9a01-e892987ee43e:a5af37a4-753d-4701-8518-be23920ac3a0/view?token=628fa483-a473-4408-bac7-7501e81b32e3"
 */
Did this help?

deleteInvoice( )

Deletes an invoice by ID.

The deleteInvoice() function returns a Promise that resolves when the invoice with the specified ID is deleted.

Method Declaration
Copy
function deleteInvoice(id: string): Promise<void>;
Method Parameters
idstringRequired

ID of the invoice to delete.

Delete invoice by ID
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const deleteInvoice = webMethod(Permissions.Anyone, (id) => {
  return invoices.deleteInvoice(id);
});
Did this help?

getInvoice( )

Gets an existing invoice by ID.

The getInvoice() function returns a Promise that resolves to the invoice with the specified ID.

Method Declaration
Copy
function getInvoice(id: string): Promise<Invoice>;
Method Parameters
idstringRequired

ID of the invoice to get.

Returns
Return Type:Promise<Invoice>
Get invoice by ID
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const getInvoice = webMethod(Permissions.Anyone, (id) => {
  return invoices.getInvoice(id);
});

/* Promise resolves to:
 *
 * {
 *   "id":{
 *     "id": "411a5551-b0f6-4826-8a41-ebae2879f857",
 *     "version": 25
 *   },
 *   "status": "Draft",
 *   "number": "0000001",
 *   "title": "My Invoice",
 *   "currency": "USD",
 *   "customer": {
 *     "contactId": "4f7c6637-0657-4696-a00b-9bc2ae4e035d",
 *     "email": "john.doe@somedomain.com",
 *     "address": {
 *       "country": "USA",
 *       "subdivision": "NY",
 *       "city": "New York",
 *       "postalCode": "10011",
 *       "streetAddress": {
 *         "value": "235 W 23rd St",
 *         "type": "Name"
 *       },
 *       "addressLine": "someStreet",
 *       "formatted": "235 W 23rd St, New York, NY 10011, USA"
 *     },
 *     "billingAddress": {
 *       "country": "USA",
 *       "streetAddress": {
 *         "value": "235 W 23rd St",
 *         "type": "Name"
 *       },
 *       "addressLine": "235 W 23rd St, New York, NY 10011, USA",
 *       "postalCode": "10011",
 *       "subdivision": "NY",
 *       "city": "New York",
 *       "formatted": "235 W 23rd St, New York, NY 10011, USA"
 *     },
 *     "shippingAddress": {
 *       "country": "USA",
 *       "streetAddress": {
 *         "value": "235 W 23rd St",
 *         "type": "Name"
 *       },
 *       "addressLine": "235 W 23rd St, New York, NY 10011, USA",
 *       "postalCode": "10011",
 *       "subdivision": "NY",
 *       "city": "New York",
 *       "formatted": "235 W 23rd St, New York, NY 10011, USA"
 *     },
 *     "phone": "5555555555",
 *     "company": "Some Company",
 *     "companyId": "Some Company Id",
 *     "fullName": "John Doe",
 *     "firstName": "John",
 *     "lastName": "Doe"
 *   },
 *   "dates": {
 *     "issueDate": 2019-03-13T00:00:00.000Z,
 *     "dueDate": 2019-06-12T00:00:00.000Z,
 *     "lastSeenDate": 2019-03-14T00:00:00.000Z
 *   },
 *   "discount": {
 *     "value": 2.5,
 *     "type": "Fixed"
 *   },
 *   "lineItems":[
 *     {
 *       "id": "00001",
 *       "name": "Item 1",
 *       "description": "First Item",
 *       "price": 10.5,
 *       "quantity": 3,
 *       "taxes": [
 *         {
 *           "name": "tax name",
 *           "rate": 8.5,
 *           "code": "tax code"
 *         }
 *       ]
 *     },
 *     {
 *       "id": "00002",
 *       "name": "Item 2",
 *       "description": "Second Item",
 *       "price": 50,
 *       "quantity": 1,
 *       "taxes": [
 *         {
 *           "name": "tax name",
 *           "rate": 8.5,
 *           "code": "tax code"
 *         }
 *       ]
 *     }
 *   ],
 *   "locale": {
 *     "language": "en"
 *   },
 *   "payments": [{
 *     "id": "4j9q4o00-4205-8q83-003d-3ofd9d8wmf0w",
 *     "type": "offline",
 *     "amount": "25.50",
 *     "date": 2019-03-23T00:00:00.000Z"
 *   }],
 *   "totals": {
 *     "discountAmount": null,
 *     "taxedAmount": 6.93,
 *     "fees": [],
 *     "subtotal": 81.5,
 *     "total": 88.43
 *   },
 *   "dynamicTotals": {
 *     "paidAmount": 25.50,
 *     "balance": 62.39
 *   },
 *   "taxes": [
 *     {
 *       "name": "tax name",
 *       "rate": 8.5,
 *       "taxable": 81.5,
 *       "taxed": 6.93,
 *       "code": "tax code"
 *     }
 *   ],
 *   "metadata": {
 *     "notes": "Some note",
 *     "legalTerms": "Some legal terms",
 *     "sourceUrl": "http://legalurl.com",
 *     "source": "Some source",
 *     "sourceRefId": "Some source ref id"
 *   },
 *   "companyId": "Some company id",
 *   "wasSent": true
 * }
 */
Did this help?

sendInvoice( )

Sends an invoice preview link to a customer via email.

The sendInvoice() function returns a Promise that resolves when the invoice with the specified ID and version is sent to the customer listed on the invoice.

Use the emailOptions parameter to specify the subject and body of the email sent to the customer.

Method Declaration
Copy
function sendInvoice(id: IdAndVersion, emailInfo: EmailInfo): Promise<void>;
Method Parameters
idIdAndVersionRequired

ID and version of the invoice to send.

emailInfoEmailInfoRequired

Information used when sending the email.

JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const sendInvoiceToCustomer = webMethod(
  Permissions.Anyone,
  (id, version, subject, body) => {
    const idAndVersion = {
      id: id,
      version: version,
    };

    const emailInfo = {
      subject: subject,
      body: body,
    };

    return invoices.sendInvoice(idAndVersion, emailInfo);
  },
);
Did this help?

updateInvoice( )

Update an existing invoice.

The updateInvoice() function returns a Promise that resolves to the ID and version of the updated invoice.

Note: The customer listed on the invoice must be an existing site contact or member.

Method Declaration
Copy
function updateInvoice(
  id: IdAndVersion,
  invoiceFields: InvoiceFields,
  fieldMask: Array<string>,
): Promise<Response>;
Method Parameters
idIdAndVersionRequired

ID and version of the invoice to update.

invoiceFieldsInvoiceFieldsRequired

The data used to update the invoice.

fieldMaskArray<string>

Fields to update in the invoice. If not specified, all fields update.

One of:

  • "customer"
  • "lineItems"
  • "number"
  • "locale"
  • "discount"
  • "title"
  • "currency"
  • "issueDate"
  • "dueDate"
  • "taxes"
  • "totals.total"
  • "totals.subtotal"
  • "totals.subtotal"
  • "totals.fees"
  • "metadata.notes"
  • "metadata.legalTerms"
  • "metadata.sourceUrl"
  • "metadata.sourceProperties"
  • "metadata.source"
  • "metadata.sourceRefId"
Returns
Return Type:Promise<Response>
Update an existing invoice
JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const updateInvoice = webMethod(Permissions.Anyone, (id) => {
  return invoices.getInvoice(id).then((result) => {
    //make some changes
    result.metadata.notes = "An updated note.";

    let updateFields = {
      title: result.title,
      customer: result.customer,
      currency: result.currency,
      lineItems: result.lineItems,
      discount: result.discount,
      payments: result.payments,
      metadata: result.metadata,
      dates: result.dates,
    };
    return invoices.updateInvoice(result.id, updateFields);
  });
});

/* Promise resolves to:
 * {
 *   {
 *     "id": {
 *       "id": "1ed3a515-24f9-4039-8937-2e69b6a2f33a",
 *       "version": 31
 *     }
 *   }
 * }
 */
Did this help?

voidInvoice( )

Voids an invoice.

The voidInvoice() function returns a Promise that resolves when the invoice with the specified ID is voided.

Calling voidInvoice() on a draft invoice causes an error.

Method Declaration
Copy
function voidInvoice(id: IdAndVersion): Promise<void>;
Method Parameters
idIdAndVersionRequired

ID and version of the invoice to void.

JavaScript
import { Permissions, webMethod } from "wix-web-module";
import { invoices } from "wix-billing-backend";

export const voidInvoice = webMethod(Permissions.Anyone, (id) => {
  return invoices.getInvoice(id).then((result) => {
    return invoices.voidInvoice(result.id);
  });
});
Did this help?