Invoice

Manage Invoices.

get
Show Invoice

https://api.clubcollect.com/api/v2/invoices/:id
Fetch Invoice details.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Headers
Authorization
required
string
ApiKey <api_key>
Content-Type
optional
string
Must be application/json.
Query Parameters
api_key
optional
string
Partner API Key (Deprecated)
Response
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"invoice_number": "123456",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
"invoice_lines": [
{
"invoice_line_id": "...",
"type": "INVOICE-LINE",
"amount_cents": 10000,
"description": "Membership fee",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "CREDIT-LINE",
"amount_cents": -1000,
"description": "Deduction",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "PAYMENT-LINE",
"payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "CHARGEBACK-LINE",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "CHARGEBACK-FEE-LINE",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "CHARGEBACK-FEE-PAYMENT-LINE",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "LATE-PAYMENT-FEE-LINE",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "LATE-PAYMENT-FEE-PAYMENT-LINE",
"payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "INSTALLMENT-FEE-LINE",
"amount_cents": 123,
"description": "...",
"date": "..."
},
{
"invoice_line_id": "...",
"type": "INSTALLMENT-FEE-PAYMENT-LINE",
"payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
"amount_cents": 123,
"description": "...",
"date": "..."
}
],
"amount_total_cents": "...",
"messages": [
{
"message_id": "...",
"type": "EMAIL|SMS|LETTER",
"description": "...",
"date": "..."
},
{
"message_id": "...",
"type": "EMAIL|SMS|LETTER",
"description": "...",
"date": "..."}
],
"tickets": [
{
"ticket_id": "...",
"message": "I don't want to pay",
"sender": "CUSTOMER",
"date": "..."
},
{
"ticket_id": "...",
"message": "You really must pay",
"sender": "COMPANY",
"date": "..."}
],
"retracted_at": null | "...",
"retraction_reason": null | "...",
"show_retraction_reason_to_customer": true | false
}
404: Not Found
{
"error": "invalid_invoice_id"
}

Note the date format is ISO 8601.

Note a Partner usually calls the GET /v2/invoices/:id method in response to a notification sent by ClubCollect about an update to an Invoice.

Note To get a list of possible values for invoice lines types see the Invoice Line documentation.

post
Create Invoice

https://api.clubcollect.com/api/v2/invoices
Create an Invoice with one or more Invoice Lines.
Request
Response
Request
Headers
Authorization
required
string
ApiKey <api_key>
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
optional
string
Partner API Key (Deprecated)
Body Parameters
locale
optional
string
When supplied, the invoice's locale will be set to this value. From { de en fr it nl }
direct_debit_iban
optional
string
When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.
federation_membership_number
optional
string
club_membership_number
optional
string
member_external_id
optional
string
external_membership_number
optional
string
invoice_lines[].invoice_line_id
optional
string
Optionally specify a custom identifier to overwrite an otherwise randomly generated identifier. If given, the partner must ensure that the ID is unique. Requests with duplicate IDs will be rejected.
amount_total_cents
required
number
Must be equal to the sum of the amounts of the Invoice Lines. May be zero or negative.
invoice_lines
required
array
customer.address.country_code
required
string
May be empty if `email_address` or `phone_number` is provided
customer.address.city
required
string
May be empty if `email_address` or `phone_number` is provided
customer.address.zipcode
required
string
May be empty if `email_address` or `phone_number` is provided
customer.address.address1
required
string
May be empty if `email_address` or `phone_number` is provided
customer.address.address2
optional
string
customer.address.house_number
optional
string
customer.address.house_number_extension
optional
string
customer.address.locality
optional
string
customer.address.state
optional
string
customer.phone.country_code
required
string
May be empty if `email_address` or a postal address is provided
customer.phone.phone_number
required
string
May be empty if `email_address` or a postal address is provided
customer.email.email_address
required
string
May be empty if `phone_number` or a postal address is provided
customer.name.last_name
required
string
customer.name.organization
optional
string
external_invoice_number
required
string
reference
optional
string
import_id
required
string
ID of Import to which the Invoice should belong.
Response
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"invoice_number": "123456",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
"invoice_lines": [
{
"invoice_line_id": "...",
"type": "INVOICE-LINE",
"amount_cents": 10000,
"description": "Membership fee",
"date": "..."
},
{
"invoice_line_id": "...",
"amount_cents": -1000,
"description": "Deduction",
"date": "..."
}
],
"amount_total_cents": 9000,
"tickets": [],
"messages": []
}

Example Request Body

{
"import_id": "...",
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"locale": "en",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
"invoice_lines": [
{
"invoice_line_id": "...",
"amount_cents": 10000,
"description": "Membership fee",
"date": "..."
},
{
"invoice_line_id": "...",
"amount_cents": -1000,
"description": "Deduction",
"date": "..."
}
],
"amount_total_cents": 9000
}

Error Messages

  • invalid_import_id: No import with this ID could be found.

  • invalid_external_invoice_number: formatting error: min. 1 character.

  • invalid_customer_last_name: Last name may not be empty.

  • invalid_customer_email: Email address may not be empty if no phone number is provided.

  • invalid_customer_phone: Phone number may not be empty if no email address is provided.

  • invalid_customer_address: Address may not be empty if neither an email address nor phone number is provided.

  • invalid_amount_total_cents: amount_total_cents is not equal to the total of all invoice line amounts.

  • duplicate_invoice_line_id: The duplicate_invoice_line_id provided was already used for another invoice line.

  • invalid_content_type: Content-Type: application/json must be provided.

Note the total may be zero (nothing to receive) or negative (something to receive).

Note at least one of:

  • customer.email.email_address

  • customer.phone.*

  • customer.address.*

must be provided. i.e. there must be a way for us to contact the Customer via email, phone or postal mail.

Note It's not possible to add or delete invoice lines for an existing invoice. If an invoice is incorrectly created with a wrong amount outstanding (or the invoice becomes invalid for some reason after it's transmitted), the partner can credit it using /credit_and_retract endpoint.

put
Update Invoice

https://api.clubcollect.com/api/v2/invoices/:id
Update a subset of Invoice attributes.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Headers
Authorization
required
string
ApiKey <api_key>
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
optional
string
Partner API Key (Deprecated)
Body Parameters
locale
optional
string
When supplied, the invoice's locale will be set to this value. From { de en fr it nl }
direct_debit_iban
optional
string
When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.
federation_membership_number
optional
string
club_membership_number
optional
string
member_external_id
optional
string
external_membership_number
optional
string
customer.address.country_code
optional
string
customer.address.city
optional
string
customer.address.zipcode
optional
string
customer.address.address1
optional
string
customer.address.address2
optional
string
customer.address.house_number
optional
string
customer.address.house_number_extension
optional
string
customer.address.locality
optional
string
customer.address.state
optional
string
customer.phone.country_code
optional
string
customer.phone.phone_number
optional
string
customer.email.email_address
optional
string
customer.name.last_name
optional
string
customer.name.organization
optional
string
external_invoice_number
required
string
reference
optional
string
Response
200: OK
{
"import_id": "...",
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"invoice_number": "123456",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
"invoice_lines": [
{
"invoice_line_id": "...",
"type": "INVOICE-LINE",
"amount_cents": 10000,
"description": "Membership fee",
"date": "..."
},
{
"invoice_line_id": "...",
"amount_cents": -1000,
"description": "Deduction",
"date": "..."
}
],
"amount_total_cents": 9000,
"tickets": [],
"messages": []
}
404: Not Found
{
"error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
"error": "invalid_external_invoice_number"
}

Example Request Body

{
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
}

Error Messages

  • invalid_invoice_id: No invoice with this invoice_id could be found.

  • invalid_external_invoice_number: formatting error: min. 1 character.

  • invalid_customer_last_name: Last name may not be empty.

  • invalid_customer_email: Email address may not be empty if no phone number is provided.

  • invalid_customer_phone: Phone number may not be empty if no email address is provided.

  • invalid_content_type: Content-Type: application/json must be provided.

post
Credit and Retract Invoice

https://api.clubcollect.com/api/v2/invoices/:id/credit_and_retract
Call this method to credit the total outstanding amount of an invoice and retract it in a single HTTP request. Any payment decision made for the invoice will be cancelled. Additional fees that might be due will be credited automatically. It won't be possible to apply more credits to the invoice.
Request
Response
Request
Path Parameters
id
required
string
ID of the Invoice to be retracted.
Headers
Authorization
required
string
ApiKey <api_key>
Content-Type
required
string
Must be application/json.
Query Parameters
api_key
optional
string
Partner API Key (Deprecated)
Body Parameters
show_retraction_reason_to_customer
optional
boolean
external_invoice_number
required
string
retraction_reason
optional
string
description
required
string
Response
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"reference": "ba6fe77",
"invoice_number": "123456",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"member_external_id": "...",
"external_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe",
"organization": "TheClub"
},
"address": {
"address1": "3rd Avenue",
"address2": "",
"locality": "",
"house_number": "1500",
"state": "",
"zipcode": "10010",
"city": "Amsterdam",
"country_code": "NL"
},
"email": {
"email_address": "joe@example.com"
},
"phone": {
"phone_number": "562-756-2233",
"country_code": "NL"
}
},
"invoice_lines": [
{
"invoice_line_id": "...",
"type": "INVOICE-LINE",
"amount_cents": 10000,
"description": "Membership fee",
"date": "..."
},
{
"invoice_line_id": "...",
"amount_cents": -1000,
"description": "Deduction",
"date": "..."
}
],
"amount_total_cents": 9000,
"tickets": [],
"messages": []
}
404: Not Found
{
"error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
"error": "payment_in_progress"
}

Example Request Body

{
"external_invoice_number": "2014-342-545",
"description": "Cash payment",
"retraction_reason": "Paid by cash",
"show_retraction_reason_to_customer": true
}

Error Messages

  • invalid_invoice_id: No invoice with this ID could be found.

  • invalid_external_invoice_number: min. 1 character

  • invalid_description: description must be provided.

  • already_retracted: The invoice with this ID has already been retracted.

  • invalid_content_type: Content-Type: application/json must be provided.

  • payment_in_progress: An invoice can't be credited or retracted if there's a payment in progress

delete
Delete Invoice

https://api.clubcollect.com/api/v2/invoices/:id
Deletes an invoice. Deleting an invoice is possible only when it's not transmitted yet.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Headers
Authorization
required
string
ApiKey <api_key>
Query Parameters
api_key
optional
string
Partner API Key (Deprecated)
Response
204: No Content
Invoice successfully deleted.
404: Not Found
{
"error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
"error": "invoice_already_transmitted"
}