Follow

Invoices API call

You can use the Invoices API call to retrieve information on a particular invoice, or for multiple invoices, filtered by date, contact, event, or unpaid invoices. You can also create, edit, void, or delete an invoice.

Wild Apricot's API is intended for use by developers with technical expertise. If you need assistance, we provide support via email or through our Developers forum.

Retrieving information for a specific invoice

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/[invoiceID]
Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/206311

Retrieving multiple invoices

You can use the Invoices API call to retrieve multiple invoices. You must include filter criteria to narrow the results. For details, see Filtering the results (below).

The invoice IDs will be listed by document date in descending order.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/?[filterCriteria]
Example:
GET https://api.wildapricot.org/v2.1/Accounts/58293/Invoices?contactId=725191&StartDate=2016-11-20 

If you want to retrieve voided invoices as well as active invoices, specify v2.1 as the API version.

Parameters

The following parameters are used within the Invoices API call:

baseAPIaddress
The base address of the API. For more information, see API access options.

version
The version number of the API. Versions 2 and 2.1 are supported for this call. To retrieve a list of API versions, use the Base API call.

accountID
The account identifier that is returned by the Accounts API call.

invoiceID
The unique identifier for an invoice. Invoices IDs are returned by the Invoices API call.

filterCriteria
The criteria used to filter the search results. This is a required parameter. For details, see Filtering the results (below).

Each API call must include an authentication information that verifies your account and prevents others from accessing your data. For more information, see API access options.

Filtering the results

When retrieving information for multiple invoices, you must include filter criteria. You can filter the results by specifying a contact or event, by specifying a start and/or end date, and by specifying a set of invoice ids. You can also filter the list to retrieve only unpaid invoices. You can combine multiple filter criteria to further narrow the results.

Specifying a contact or event

You can filter the invoices by specifying a particular contact and/or event.

Syntax
GET [baseAPIaddress]/[version}/Accounts/[accountID]/Invoices/?contactId=[contactID]&eventId=[eventID]
Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/?contactId=725191&eventId=11769

Specifying a start or end document date

You can filter the invoices by specifying a start date and/or an end date (using the DocumentDate field).

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/?StartDate=[date]&EndDate=[date]

where date is the start or end date of the range (using the yyyy-mm-dd date format).

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/?StartDate=2016-11-01&EndDate=2016-11-30

Specifying a set of invoice IDs

You can filter the invoices by specifying a set of invoice IDs.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/?ids=[id1],[id2],[id3]...

where id is the unique identifier of an invoice.

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/?ids=206311,206312

Retrieving only unpaid invoices

You can filter the invoices to retrieve only invoices without settled payments.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/?UnpaidOnly

where id is the unique identifier of an invoice.

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/?UnpaidOnly

Retrieving just invoice IDs

You can retrieve just the invoice IDs that match the filter criteria by including the idsOnly parameter. This parameter is only available when you specify v2.1 as the API version. The invoice IDs will be listed by document date in descending order.

Example
GET https://api.wildapricot.org/v2/Accounts/58293/Invoices/?eventId=11769&idsOnly=true

Paging

Using the $skip and $top parameters, you can retrieve records in sets or pages. You use the $top parameter to specify the maximum number of records to be returned, and the $skip parameter to specify the number of records to skip. The $skip parameter is incremented each call to return the next set or page of records.

Example

You want to retrieve 50 records using an application that can only process 20 records at a time. Using the following calls, the application retrieves the first set of 20 records, then a second set of 20, and finally, the remaining 10 records.

https://api.wildapricot.org/v2/Accounts/58293/Invoices?eventId=11769&$skip=0&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Invoices?eventId=11769&$skip=20&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Invoices?eventId=11769&$skip=40&$top=20

In this example, the $top specifies the maximum number of records to retrieve (20), and the $skip parameter is incremented from 0 to 20 to 40 to skip the recordsretrieved by the previous call(s).

Response fields

For each invoice, the Invoices API call retrieves the following information.

Contact
The contact to whom the invoice is assigned. You must specify the contact when adding an invoice.

CreatedBy
The contact who created the invoice (if manually created).

CreatedDate
The date the invoice was created.

DocumentDate
The date and time the invoice was created.

DocumentNumber
The invoice number.

ID
The unique identifier of the invoice.

IsPaid
Indicates whether the invoice is fully paid.

Memo
Internal notes on the invoice.

OrderDetails
Details of the individual items appearing on the invoice. This is a required array when adding an invoice. Within the OrderDetails array, the fields are Value, Notes, and Taxes. Notes are required and the sum of the Value fields must be positive.

OrderType
The invoice type. Possible values:

  • ChangeBillingPlan
  • ChangeBillingInfo
  • Donation
  • EventRegistration
  • MembershipApplication
  • MembershipLevelChange
  • MembershipRenewal
  • Undefined

PaidAmount
The sum paid towards the invoice.

PublicMemo
Comments for the payer on the invoice.

UpdatedBy
The contact who updated the invoice.

UpdatedDate
The date the invoice was last updated.

Value
The total amount of the invoice.

URL
The address of the URL call for the invoice.

Sample JSON response

 {
"DocumentNumber": "00004",
"IsPaid": true,
"PaidAmount": 84,
"OrderType": "EventRegistration",
"EventRegistration": {
"Id": 13914620,
"Url": "http://api.wildapricot.org/v2.1/accounts/203011/EventRegistrations/13914620"
},
"OrderDetails": [
{
"Value": 84,
"Notes": "Registration for "Spring Gala" (1 Apr 2019 7:30 PM, The Event Venue), Member tickets",
"Taxes": {
"Value": 84,
"CalculatedTax1": 4,
"CalculatedTax2": 0,
"NetAmount": 80,
"RoundedAmount": 84,
"Tax1": {
"Name": "GST",
"PublicId": "",
"Rate": 5
},
"Tax2": null
}
}
],
"Memo": "Payer is frequently late",
"PublicMemo": "Please pay online",
"Value": 84,
"DocumentDate": "2016-11-21T00:00:00-05:00",
"Contact": {
"Id": 29976959,
"Url": "http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976959"
},
"CreatedDate": "2016-11-21T13:24:38",
"CreatedBy": {
"Id": 29976949,
"Url": "http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949"
},
"UpdatedDate": "2016-11-21T13:24:56",
"UpdatedBy": {
"Id": 29976949,
"Url": "http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949"
},
"Id": 25291893,
"Url": "http://api.wildapricot.org/v2.1/accounts/203011/Invoices/25291893"
}

Sample XML response

<Invoice xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.wildapricot.org">
<Id>25291893</Id>
<Url>http://api.wildapricot.org/v2.1/accounts/203011/Invoices/25291893</Url>
<Contact>
<Id>29976959</Id>
<Url>http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976959</Url>
</Contact>
<CreatedBy>
<Id>29976949</Id>
<Url>http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949</Url>
</CreatedBy>
<CreatedDate>2016-11-21T13:24:38</CreatedDate>
<DocumentDate xmlns:d2p1="http://schemas.datacontract.org/2004/07/System">
<d2p1:DateTime>2016-11-21T05:00:00Z</d2p1:DateTime>
<d2p1:OffsetMinutes>-300</d2p1:OffsetMinutes>
</DocumentDate>
<UpdatedBy>
<Id>29976949</Id>
<Url>http://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949</Url>
</UpdatedBy>
<UpdatedDate>2016-11-21T13:24:56</UpdatedDate>
<Value>84.0000</Value>
<DocumentNumber>00004</DocumentNumber>
<EventRegistration>
<Id>13914620</Id>
<Url>http://api.wildapricot.org/v2.1/accounts/203011/EventRegistrations/13914620</Url>
</EventRegistration>
<IsPaid>true</IsPaid>
<Memo>Payer is frequently late</Memo>
<OrderDetails>
<OrderDetail>
<Notes>Registration for "Spring Gala" (1 Apr 2019 7:30 PM, The Event Venue), Member tickets</Notes>
<Taxes>
<Amount>84.0000000</Amount>
<CalculatedTax1>4.0000000</CalculatedTax1>
<CalculatedTax2>0</CalculatedTax2>
<NetAmount>80.0000</NetAmount>
<RoundedAmount>84.00</RoundedAmount>
<Tax1>
<Name>GST</Name>
<PublicId>
</PublicId>
<Rate>5.000</Rate>
</Tax1>
<Tax2 i:nil="true" />
</Taxes>
<Value>84.0000</Value>
</OrderDetail>
</OrderDetails>
<OrderType>EventRegistration</OrderType>
<PaidAmount>84.0000</PaidAmount>
<PublicMemo>Please pay online</PublicMemo>
<VoidedDate i:nil="true" />
</Invoice>

Creating a new invoice

You can use the Invoices API call to create a new invoice.

Syntax
POST [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices
{
"[invoiceField]": [invoiceFieldValue],
"[invoiceField]": [invoiceFieldValue],
...
}

where invoiceField is a field returned by the Invoices API call.

Example
POST https://api.wildapricot.org/v2/Accounts/58293/Invoices
{
"OrderDetails": [
{
"Value": 25,
"Quantity": 1,
"Notes": "Membership level change. New level: Gold"
}
],
"Contact": {
"Id": 29976959
},
"CreatedDate": "2016-11-21T13:24:38",
"CreatedBy": {
"Id": 29976949
}
}
The OrderDetails array, and the Contact ID are required when adding an invoice. Within the OrderDetails array, the fields are Value, Notes, and Taxes. Notes are required and the sum of the Value fields must be positive.

If successful, the call will return the new invoice ID.

Updating an invoice

You can update an existing invoice using an Invoices API call.

Syntax
PUT [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/[invoiceID]
{
"Id": invoiceID,
"[invoiceField]": [invoiceFieldValue],
"[invoiceField]": [invoiceFieldValue],
...
}

where invoiceField is a field returned by the Invoices API call.

The invoice ID must be specified both as a field and within the requesting URL. All other fields are optional.
Example
PUT https://api.wildapricot.org/v2/Accounts/58293/Invoices/206311
{
"OrderDetails": [
{
"Value": 25,
"Notes": "Membership level change. New level: Gold"
}
],
"CreatedDate": "2016-11-21T13:24:38",
"CreatedBy": {
"Id": 29976949
}
}

If successful, the call returns an HTTP status code 200 without any data in the response body.

Voiding an invoice

You can perform a remote procedure call to void an invoice.

Syntax
POST [baseAPIaddress]/[version]/rpc/[accountID]/VoidInvoice?invoiceId=[invoice_id]

where invoiceID is the unique identifier of an invoice returned by the Invoices API call.

Example
POST https://api.wildapricot.org/v2/rpc/58293/VoidInvoice?invoiceId=206311

Deleting an invoice

You can use an Invoices API call to delete an existing invoice.

Syntax
DELETE [baseAPIaddress]/[version]/Accounts/[accountID]/Invoices/[invoiceID]

where invoiceID is the ID of the invoice you want to delete.

Example
DELETE https://api.wildapricot.org/v2/Accounts/58293/Invoices/206311

If successful, the call returns HTTP 200 Success. If unsuccessful, returns HTTP 400 bad request.

Generating an invoice for an event registration

You can perform a remote procedure call to generate or regenerate an invoice for an event registration.

Syntax
POST [baseAPIaddress]/[version]/rpc/[accountID]/GenerateInvoiceForEventRegistration?eventRegistrationId=[eventRegistrationID]&updateIfExists=true/false

where eventRegistrationsID is the unique identifier of an event registration returned by the EventRegistrations API call, and updateIfExists is an optional parameter. If updateIfExists=true, then the invoice will be regenerated if it already exists. If updateIfExists=false and the invoice already exists, then Bad request will be returned.

Example
POST https://api.wildapricot.org/v2/rpc/58293/GenerateInvoiceForEventRegistration?eventRegistrationId=112745&updateIfExists=true

If this call is successful, it returns the ID of the new or updated invoice.

0 Comments

Please sign in to leave a comment.

Search: WildApricot.com 

About results ( seconds) Sort by: 
Sorry, an error occured when performing search.