Chargebee
Chargebee is a subscription billing and revenue management platform. It helps companies offering subscription services automate their billing procedures.
Data integration: Skyvia supports importing data to and from Chargebee, exporting Chargebee data to CSV files, replicating Chargebee data to relational databases, and synchronizing Chargebee data with other cloud apps and relational databases.
Backup: Skyvia Backup does not support Chargebee backup.
Query: Skyvia Query supports Chargebee.
Establishing Connection
To create a connection with Chargebee, you need to know the API key and Subdomain values.
Getting credentials
Subdomain is a value that comes in the URL before chargebee.com. For example, if your Chargebee link looks like this: https://test-account.chargebee.com, use test-account as your Subdomain.
API Key is a key that is used to authenticate Skyvia and control your access to the Chargebee.
To locate your API Key, perform the following steps:
- Log in to your Chargebee account.
- Click the gear icon on the left to navigate to Settings -> select Configure Chargebee and scroll down to API Keys and Webhooks.
-
Click API Keys. Copy the available API Key or create a new one.
Creating Connection
Paste the obtained Subdomain and API Key to the corresponding boxes of the Connection Editor in Skyvia.
Connector Specifics
Object Specifics
Coupons
To import records to the Coupons object, you must map either the DiscountAmount or DiscountPercentage field value. It depends on whether DiscountType is set to Fixed Amount or Percentage.
Additionally, if the ApplyOn value is set to Each Specified Item, you need to map one of two columns: ItemConstraints or ItemConstraintCriteria. Otherwise, the Import generates an error “Constraint should be passed for at least one item_type, or it has to be all/specific/criteria.”
CreditNotes
To import records to the CreditNotes in addition to the required ReferenceInvoiceId field, you must map either Total or LineItems field. Also, depending on your account settings, you may need to map the CreateReasonCode if it is set as mandatory in Chargebee.
Invoices
To import records to the Invoices object, you must map either the CustomerId or SubscriptionId fields. Additionally, you must map either the Charges or LineItems array field. Find an entry with ItemType = Charge in the ItemPrices table, copy the value from the Id column, and paste it to the LineItems array as item_price_id.
Quotes
To import records to the Quotes table, you must map either the ItemPrices or the Charges additionally to the required CustomerId field. Otherwise, the Import generates the error “At least one nonrecurring addon or charge item should be present.”
UnbilledCharges
To import records to the UnbilledCharges, besides the required SubscriptionId field, you also must map either the ItemPrices or the Charges field.
Charges value example: [{“amount”:77, “description”: “test import”}]
ItemPrices value example: [{“item_price_id”: “item_pr_1”}]
VirtualBankAccounts
Email field is not required for VirtualBankAccounts as its value is taken from the Customers object. However, if Email is not specified in Customers, you will receive an error “virtual_bank_account[email] : cannot be blank.”
Incremental Replication and Synchronization
Replication with Incremental Updates is supported for the following objects: Comments, Coupons, CreditNotes, Customers, Gifts, InvoiceLinkedOrders, Invoices, ItemFamilies, ItemPrices, Items, Orders, PaymentSources, Quotes, Subscriptions, Transactions, UnbilledCharges, VirtualBankAccounts.
Synchronization is supported for the following objects: Customers, Gifts, Invoices, PaymentSources, Quotes, Subscriptions.
The Id value in Coupons, ItemFamilies, Items and ItemPrices objects is not autogenerated and should be set manually. Thus Synchronization of Coupons, ItemFamilies, Items and ItemPrices objects cause an error “Required column ‘Id’ is missing.”
DML Operations
Skyvia supports the following DML operations for Chargebee objects:
| Operation | Object |
|---|---|
| INSERT, UPDATE, DELETE | Coupons, CouponSets, CustomerContacts, Customers, Invoices, ItemFamilies, ItemPrices, Items, Orders, PaymentSources, Quotes, Subscriptions |
| INSERT, DELETE | Comments, CreditNotes, UnbilledCharges, VirtualBankAccounts |
| INSERT, UPDATE | Gifts |
Stored Procedures
Skyvia represents part of the supported Chargebee features as stored procedures. You can call a stored procedure, for example, as a text of the command in the ExecuteCommand action in a Target component of a Data Flow or in Query.
CopyCoupon
The following command copies a coupon from one site to another. Copying of archived coupons is not supported.
call CopyCoupon(:from_site, :id_at_from_site)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| From_site | Your Chargebee site name having the coupon to be copied. |
| Id_at_from_site | Id of the coupon to be copied |
UnarchiveCoupon
To unarchive a specific coupon using the coupon Id, use the command
call UnarchiveCoupon(:coupon_id)
DeleteUnusedCouponCodes
The following command deletes all the unutilized coupon codes from a specific coupon set
call DeleteUnusedCouponCodes(:coupon_set_id)
ArchiveCouponCode
To archive a coupon code thereby making it inactive. The archived coupon code cannot be applied to any subscription.
call ArchiveCouponCode(:coupon_code)
UpdatePaymentMethodForCustomer
To update payment method details for a customer, use command
call UpdatePaymentMethodForCustomer(:customer_id, :payment_method_type, :payment_method_reference_id)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Customer_id | The Chargebee customer’s identifier |
| Payment_method_type | Type of payment source (Enum). Valid values are card, paypal_express_checkout, amazon_payments, direct_debit, generic, alipay, unionpay, wechat_pay, ideal, google_pay, sofort, bancontact, giropay, dotpay, upi, netbanking_emandates |
| Payment_method_reference_id | The reference Id. In the case of Amazon and PayPal this will be the billing agreement Id. For GoCardless direct debit this will be ‘mandate Id’. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. |
UpdateBillingInfoForCustomer
Use the following command to update the billing information for customer, including billing_address and vat_number attributes of the customer.
call UpdateBillingInfoForCustomer(:customer_id, :vat_number, :vat_number_prefix, :entity_identifier_scheme, :entity_identifier_standard, :registered_for_gst, :business_customer_without_vat_number, :is_einvoice_enabled, :billing_address_first_name, :billing_address_last_name, :billing_address_email, :billing_address_company, :billing_address_phone, :billing_address_line1, :billing_address_line2, :billing_address_line3, :billing_address_city, :billing_address_state_code, :billing_address_state, :billing_address_zip, :billing_address_country, :billing_address_validation_status)
Though, Customer_id is the only required parameter, it is necessary to fill out all the parameters due to stored procedure specifics.
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Customer_id | The Chargebee customer’s identifier |
| Vat_number | The VAT/tax registration number for the customer |
| Vat_number_prefix | An overridden value for the first two characters of the full VAT number |
| Entity_identifier_scheme | The Peppol BIS scheme associated with the vat_number of the customer |
| Entity_identifier_standard | Currently only iso6523-actorid-upis is supported and is used by default when not provided |
| Registered_for_gst | Boolean. Confirms that a customer is registered under GST |
| Business_customer_without_vat_number | Boolean. Confirms that a customer is a valid business without an EU/UK VAT number |
| Is_einvoice_enabled | Boolean. Determines whether the customer is e-invoiced |
| Billing_address_first_name, billing_address_last_name, billing_address_email, billing_address_company, billing_address_phone, billing_address_line1, billing_address_line2, billing_address_line3, billing_address_city, billing_address_state_code, billing_address_state, billing_address_zip, billing_address_country, billing_address_validation_status | Parameters for billing_address |
More information about parameters is available here
AssignPaymentRole
The following command assigns primary or backup payment role or unassigns role for the payment source based on the preference for the payment collection.
call AssignPaymentRole(:customer_id, :payment_source_id, :role)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Customer_id | The Chargebee customer’s identifier |
| Payment_source_id | Payment source id this role will be assigned to |
| Role | Payment source role. Valid values are primary, backup, none |
RecordExcessPaymentForCustomer
The following command records any excess payments made by the customer, such as advance payments Such payments will be automatically applied to the future invoices.
call RecordExcessPaymentForCustomer(:customer_id, :comment, :transaction.amount, :transaction.currency_code, :transaction.date, :transaction.payment_method, :transaction.reference_number)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Customer_id | The Chargebee customer’s identifier |
| Comment | Сomment for an operation |
| transaction.amount | The payment transaction amount in cents |
| Transaction.currency_code | The currency code (ISO 4217 format) for the transaction. Required if Multicurrency enabled |
| Transaction.date | timestamp(UTC) in seconds |
| Transaction.payment_method | Valid values: cash, check, bank_transfer, other, custom |
| Transaction.reference_number | Reference number if needed. For example, check number in case of check payment method |
RefundCreditNote
Use the following command to refund a credit note to the payment source associated with the transaction.
call RefundCreditNote(:credit_note_id, :refund_amount, :customer_notes, :refund_reason_code)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Credit_note_id | Identifier of the credit note to be refunded |
| Refund_amount | The amount to be refunded. If not specified, the entire refundable amount for this credit_note is refunded |
| Customer_notes | The note for the operation. Available in customer-facing documents, for example credit note PDF |
| Refund_reason_code | Reason code for the refund. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Refund Credit Note |
ClaimGift
Use the following command to switch the gift status from unclaimed to to claimed:
call ClaimGift(:gift_id)
CancelGift
The following command cancels gift with specific Id.
call CancelGift(:gift_id)
You can cancel only gifts in scheduled and unclaimed states.
StopDunningForInvoice
The following command stops dunning for Payment Due invoices enabled for Auto Collection.
call StopDunningForInvoice(:invoice_id, :comment)
When dunning is stopped, the status of the invoice will be changed to Not Paid.
ApplyPaymentsForInvoice
To apply excess payments to an invoice, use the command
call ApplyPaymentsForInvoice(:invoice_id, :comment, :transactions)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Invoice_id | The identifier of the invoice to apply payment to |
| Comment | Internal сomment for the action |
| Transactions | Optional. Transactions Id or multiple Ids in the array format. Excess payments available with the customer will be applied against this invoice if this parameter is not passed. |
ApplyCreditsForInvoice
To apply available credits to an invoice, use the command
call ApplyCreditsForInvoice(:invoice_id, :comment, :credit_notes)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Invoice_id | The identifier of the invoice to apply credit to |
| Comment | Internal comment for the action |
| Credit_notes | Optional. Credit Note number or numbers in the array format. Available refundable credits with the customer will be applied against this invoice if this paramenter is not passed |
ClosePendingInvoice
To finalize a pending invoice, use command
call ClosePendingInvoice(:invoice_id, :comment, :invoice_note, :remove_general_note, :invoice_date, :notes_to_remove)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Invoice_id | The identifier of the invoice to close |
| Comment | Internal comment for the action. It is not displayed in any document |
| Invoice_note | A note for this particular invoice |
| Remove_general_note | Boolean. Removes the general note from this invoice if set to true |
| Invoice_date | Timestamp(UTC) in seconds. Must lie between the date when the invoice was generated and current date |
| Notes_to_remove | Note Id or multiple Ids in the array format |
CollectPaymentForInvoice
To collect payments for payment_due and not_paid invoices, use the command
call CollectPaymentForInvoice(:invoice_id, :amount, :authorization_transaction_id, :payment_source_id, :comment)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Invoice_id | The identifier of the invoice to collect payment for |
| Amount | Amount to be collected in cents. If this parameter is not passed then the entire amount due will be collected |
| Authorization_transaction_id | Authorization transaction to be captured |
| Payment_source_id | Payment source to be used for this payment |
| Comment | Internal comment for the action. Is not displayed in any document |
RefundInvoice
To refund invoice, use the command
call RefundInvoice(:invoice, :refund_amount, :comment, :customer_notes, :credit_note_reason_code, :credit_note_create_reason_code)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Invoice | The identifier of the invoice to be refunded |
| Refund_amount | The amount to be refunded in cents |
| Comment | Internal comment for the action |
| Customer_notes | Customer notes to be filled in Credit Note |
| Credit_note_reason_code | Valid values: *product_unsatisfactory, service_unsatisfactory, order_change, order_cancellation, waive, other |
| Credit_note_create_reason_code | Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note |
AssignOrderNumber
The following command assigns order number to the order based on the settings, if not already assigned.
call AssignOrderNumber(:order_id)
CancelOrder
To cancel order and create a refundable credit note for the order, use the command
call CancelOrder(:order_id, :cancellation_reason, :customer_notes, :comment, :cancelled_at, :credit_note_total)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Order_id | The Id of the order to be canceled |
| Cancellation_reason | Valid values: shipping_cut_off_passed, product_unsatisfactory, third_party_cancellation, product_not_required, delivery_date_missed, alternative_found, invoice_written_off, invoice_voided, fraudulent_transaction, payment_declined, subscription_cancelled, product_not_available, others, order_resent |
| Customer_notes | Customer notes to be filled in Credit Note |
| Comment | Internal comment for the action |
| Canceled_at | The time at which the order was cancelled |
| Credit_note_total | Credit Note amount in cents |
CreateAuthorizationPayment
The following command authorizes a specific amount in a customer’s Credit card, which can be collected within a period.
call CreateAuthorizationPayment(:customer_id, :payment_source_id, :currency_code, :amount)
| PARAMETER NAME | DESCRIPTION |
|---|---|
| Customer_id | Identifier of the customer |
| Payment_source_id | Payment source to be used for authorizing the transaction |
| Currency_code | The currency code (ISO 4217 format) of the transaction amount |
| Amount | The amount to be blocked |
VoidAuthorizationTransaction
The following command voids the specific authorization transaction to release blocked funds from the customer’s card.
call VoidAuthorizationTransaction(:transaction_id)
RefundPayment
The following command refunds an online payment. Applicable only for transactions of the payment type. You can only refund a transaction with a success status.
call RefundPayment(:transaction_id, :amount, :comment)
For more information about the parameters, please refer to Chargebee API documentation.
Supported Actions
Skyvia supports all the common actions for Chargebee.