Invoice

Last updated 4 months ago
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.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
Create a Credit Invoice for an existing Invoice. The Credit Invoice may contain one or more Invoice Lines. You cannot credit a Credit Invoice. Positive Invoice Line amounts are allowed provided the total amount is negative.
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