Chargebee - HackMD

# Chargebee Chargebee is a subscription billing and revenue management platform. It helps companies that offer 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. ## Chargebee Specific Features and Limitations ### Chargebee Object Specifics #### Coupons To import Coupons you need to set the value for either *DiscountAmount* or *DiscountPercentage*. It depends on whether *DiscountType* is set to *Fixed Amount* or *Percentage*. Additionally, if the *ApplyOn* value is set to *Each Specified Item* you will need to map one of two columns: *ItemConstraints* or *ItemConstraintCriteria*, otherwise, the import will generate an error "Constraint should be passed for at least one item_type or it has to be all/specific/criteria". #### CreditNotes During the CreditNotes import in addition to the ReferenceInvoiceId that is required, you need to set the value to one of two fields: Total or LineItems. Also, depending on your account settings, you may need to set the CreateReasonCode if it is set as mandatory in the app. #### Invoices -> провалидировать с Леной During the Invoices import, you need to set one of two columns: CustomerId or SubscriptionId. Additionally, during the mapping of the fields you need to set either *Charges* or *LineItems* array column. Find an entry with *ItemType* = *Charge* in the *ItemPrices* table and copy the value from the *Id* column and paste it to the *LineItems* array as *item_price_id*. #### Quotes To import Quotes, besides CustomerId that is required, you also need to set values for ItemPrices or Charges. Otherwise, you will get an error "At least one nonrecurring addon or charge item should be present". #### UnbilledCharges To import *UnbilledCharges*, besides *SubscriptionId* that is required, you also need to set values for *ItemPrices* or *Charges*. *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 the 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". ### Synchronization Specifics 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 will cause an error "Required column 'Id' is missing". ### Stored Procedures Chargebee connector supports stored procedures for several Chargebee objects. You can use them in Data Flow to expand the list of possible actions. #### Coupons * ```call CopyCoupon(:from_site, :id_at_from_site)``` --- copies a coupon from one site to another. Copying of archived coupons is not supported. * ```call UnarchiveCoupon(:coupon_id)``` --- unarchives a specific coupon using the coupon ID. #### CouponSets * ```call DeleteUnusedCouponCodes(:coupon_set_id)``` --- deletes all the unutilised coupon codes from a specific coupon set. #### CouponCodes * ```call ArchiveCouponCode(:coupon_code)``` --- archives a coupon code thereby making it inactive. The archived coupon code cannot be applied to any subscription. #### Customers * ```call UpdatePaymentMethodForCustomer(:customer_id, :payment_method_type, :payment_method_reference_id)``` --- updates payment method details for a 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)``` --- used for updating the billing_address and vat_number attributes of the customer. Customer_id is the only required parameter, however, due to stored procedure specifics, it is necessary to fill out all the parameters. * ```call AssignPaymentRole(:customer_id, :payment_source_id, :role)``` --- assigns primary or backup payment role or unassigns role for the payment source based on the preference for the payment collection. * ```call RecordExcessPaymentForCustomer(:customer_id, :comment, :transaction.amount, :transaction.currency_code, :transaction.date, :transaction.payment_method, :transaction.reference_number)``` --- records any excess payments made by the customer, such as advance payments. Such payments will be automatically applied to the future invoices #### CreditNotes * ```call RefundCreditNote(:credit_note_id, :refund_amount, :customer_notes, :refund_reason_code)``` --- refunds a credit note to the payment source associated with the transaction #### Gifts * ```call ClaimGift(:gift_id)``` --- claiming a gift with a given id will move the status to *claimed*. Only gifts in *unclaimed* state can be claimed. * ```call CancelGift(:gift_id)``` --- cancels gift with given id. Only gifts in *scheduled* and *unclaimed* states can be canceled. #### Invoices * ```call StopDunningForInvoice(:invoice_id, :comment)``` --- stops dunning for Payment Due invoices that have been enabled for Auto Collection. When dunning is stopped, the status of the invoice will be changed to Not Paid. * ```call ApplyPaymentsForInvoice(:invoice_id, :comment, :transactions)``` --- applies excess payments to an invoice. * ```call ApplyCreditsForInvoice(:invoice_id, :comment, :credit_notes)``` --- applies available credits to an invoice. * ```call ClosePendingInvoice(:invoice_id, :comment, :invoice_note, :remove_general_note, :invoice_date, :notes_to_remove)``` --- finalizes a pending invoice. * ```call CollectPaymentForInvoice(:invoice_id, :amount, :authorization_transaction_id, :payment_source_id, :comment)``` --- collects payments for payment_due and not_paid invoices. * ```call RefundInvoice(:invoice, :refund_amount, :comment, :customer_notes, :credit_note_reason_code, :credit_note_create_reason_code)``` --- refunds the invoice. #### Orders * ```call AssignOrderNumber(:order_id)``` --- assigns order number to the order based on the settings, if not already assigned. * ```call CancelOrder(:order_id, :cancellation_reason, :customer_notes, :comment, :cancelled_at, :credit_note_total)``` --- cancels order and creates a refundable credit note for the order. #### Transactions * ```call CreateAuthorizationPayment(:customer_id, :payment_source_id, :currency_code, :amount)``` --- authorizes a specific amount in customer's Credit card, which can be collected within a span of time * ```call VoidAuthorizationTransaction(:transaction_id)``` --- voids the specific authorization transaction in order to release the blocked funds from the customer’s card. * ```call RefundPayment(:transaction_id, :amount, :comment)``` --- refunds an online payment. Applicable only for transactions of type = payment. You can only refund a transaction with a *success*. ### DML Operations Skyvia supports the following DML operations for Chargebee objects: * **INSERT, UPDATE, DELETE** --- Coupons, CouponSets, CustomerContacts, Customers, Invoices, ItemFamilies, ItemPrices, Items, Orders, PaymentSources, Quotes, Subscriptions * **INSERT, DELETE** - Comments, CreditNotes, UnbilledCharges, VirtualBankAccounts * **INSERT, UPDATE** - Gifts ## Chargebee Connections To establish a connection, you need to know the API key and Subdomain values. You may find them in your Chargebee account. **Subdomain** is a subdomain 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: ![](https://i.imgur.com/NHyMuKH.png) 1. Login to your [Chargebee account](https://www.chargebee.com/). 2. Navigate to Settings > Configure Chargebee > API Keys and Webhooks. 4. Scroll down and select API Keys. 5. All the available API keys will be displayed on this page. 6. To create a new API Key, click Add API Key To create a connection between Skyvia and Chargebee: ![](https://i.imgur.com/FjhNAtC.png) 1. Select a new Chargebee connection. 2. Enter Subdomain and API Key. 4. Click **Create Connection**. ## Supported Actions and Actions Specifics Chargebee connector supports the following actions: * [Execute Command](https://docs.skyvia.com/data-integration/actions.html#execute-command) in Source, Lookup, and Target [Data Flow components](https://docs.skyvia.com/data-integration/data-flow/components.html) and in [Import](https://docs.skyvia.com/data-integration/import/how-to-create-import-task.html#advanced-task-editor-mode) and [Export](https://docs.skyvia.com/data-integration/export/how-to-create-export-task.html#advanced-task-editor-mode) tasks in the Advanced mode. * [Execute Query](https://docs.skyvia.com/data-integration/actions.html#execute-command) in Source Data Flow components and in Import and Export tasks in the Advanced mode. * [Lookup](https://docs.skyvia.com/data-integration/actions.html#lookup) in Lookup Data Flow components. * [Insert](https://docs.skyvia.com/data-integration/actions.html#insert) in Target Data Flow components. * [Update](https://docs.skyvia.com/data-integration/actions.html#update) in Target Data Flow components. * [Delete](https://docs.skyvia.com/data-integration/actions.html#delete) in Target Data Flow components.