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
Content-Type
optional
string
Must be application/json.
Query Parameters
api_key
required
string
Partner API Key
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": "...", 
  "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.
post
Create Invoice
https://api.clubcollect.com/api/v2/invoices
Create an Invoice with one or more Invoice Lines.
Request
Response
Request
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. 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
​
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": "...", 
  "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": "...", 
  "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": "...",            
      "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.
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.
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
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
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": "...", 
  "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": "...", 
  "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 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
Request
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
​
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": "...", 
  "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", 
  "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
Request
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
​
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": "...", 
  "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
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
Query Parameters
api_key
required
string
Partner API Key
Response
204: No Content
Invoice successfully deleted.
​
404: Not Found
{
  "error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
  "error": "invoice_already_transmitted"
}