Invoice

Manage Invoices.

get
Show Invoice

https://api.clubcollect.com/api/v2/invoices/:id
Fetch Invoice details.
Request
Response
Path Parameters
id
required
string
Invoice ID
Headers
Content-Type
optional
string
Must be application/json.
Query Parameters
api_key
required
string
Partner API Key
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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",
"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",
"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",
"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.

post
Create Invoice

https://api.clubcollect.com/api/v2/invoices
Create an Invoice with one or more Invoice Lines.
Request
Response
Headers
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
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.
invoice_lines[].invoice_line_id
optional
string
Optionally specify a custom identifier to overwrite an otherwise randomly generated identifier.
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
customer.address.city
required
string
customer.address.zipcode
required
string
customer.address.address1
required
string
customer.phone.country_code
required
string
May be empty if `email_address` is provided`
customer.phone.phone_number
required
string
May be empty if `email_address` is provided.
customer.email.email_address
required
string
May be empty if `phone_number` is provided.
customer.name.last_name
required
string
external_invoice_number
required
string
import_id
required
string
ID of Import to which the Invoice should belong.
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"locale": "en",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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
}

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.

  • 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.

put
Update Invoice

https://api.clubcollect.com/api/v2/invoices/:id
Update a subset of Invoice attributes.
Request
Response
Path Parameters
id
required
string
Invoice ID
Headers
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
200: OK
{
"import_id": "...",
"external_invoice_number": "2014-342-545",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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 Invoice

https://api.clubcollect.com/api/v2/invoices/:id/credit
Adds a credit to an existing Invoice. The credit may contain one or more Invoice Lines. You cannot credit an invoice that is fully credited or retracted. Positive Invoice Line amounts are allowed provided the total amount is negative and the total outstanding of the invoice is not negative after adding the invoice lines.
Request
Response
Path Parameters
id
required
string
Invoice ID for the Invoice to be credited.
Headers
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
Body Parameters
amount_total_cents
required
number
invoice_lines
required
string
external_invoice_number
required
array
200: OK
{
"import_id": "...",
"external_invoice_number": "2014-342-545",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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",
"invoice_lines": [
{
"amount_cents": -10000,
"description": "Credit membership fee"
}
],
"amount_total_cents": 0
}

Error Messages

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

  • invalid_external_invoice_number: min. 1 character

  • invalid_invoice_lines: min. 1 line

  • invalid_amount_total_cents: should be the total of all invoice line amounts

  • invalid_credit_amount: the total amount credited should be negative

  • 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

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. Only the amount without considering additional fees will be credited. It won't be possible to apply more credits to the invoice.
Request
Response
Path Parameters
id
required
string
ID of the Invoice to be retracted.
Headers
Content-Type
required
string
Must be application/json.
Query Parameters
api_key
required
string
Partner API Key.
Body Parameters
show_retraction_reason_to_customer
optional
boolean
retraction_reason
optional
string
description
required
string
200: OK
{
"invoice_id": "...",
"import_id": "...",
"external_invoice_number": "2014-342-545",
"direct_debit_iban": "...",
"federation_membership_number": "...",
"club_membership_number": "...",
"customer": {
"name": {
"prefix": "Mr",
"first_name": "Joe",
"infix": "van der",
"last_name": "Doe"
},
"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

  • 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