Becoming a Xero App partner

As a SaaS product, becoming a Xero App partner can be a valuable opportunity to integrate your software with Xero's accounting platform and offer additional benefits to your customers.

However, it's worth noting that Xero apps have a default limit of 25 active connections. Despite this, the Xero App Marketplace provides an excellent opportunity to reach a diverse range of small businesses and accounting professionals.

If you want to overcome the connection limit of 25 connections, you can apply to become a Xero App partner and have your app certified. This involves several steps, including onboarding at least 3 active customer connections in a 30-day period when your app goes through the review process. It's worth noting that the Xero App partnership entails a commercial agreement with a 15% referral revenue share for sales made through the Xero App Store.

Xero App partner steps:

1. Sign up for Xero
2. Create a Xero app
3. Onboard at least 3 active customer connections within a 30-day period
4. Submit your app for certification
5. Wait for Xero to review your application
6. Receive your Partner confirmation
7. Publish your app in the Xero App Marketplace

Once you're approved as a Xero App Partner, you'll be able to list your product in the Xero App Marketplace and benefit from Xero's extensive developer resources and support services.

For more information on the Xero App partner program, see the Xero App partner program page.

To facilitate the process of becoming a Xero App partner and get your Xero app published in the Xero App Marketplace, we strongly advise the following actions:

• Create a Xero app & connect via Apideck
• Onboard at least 3 active customer connections with your Xero app
• Customize Apideck Vault redirect URI

Create a Xero app & connect via Apideck

To create a connection with Xero, you have to complete these steps.

Sign up for Xero

Go to the Xero website (www.xero.com) and click on the "Sign up" button to become a partner.

Fill out the sign-up form with your details and click "Submit". You should receive a verification email. Open the verification email and click on the link to complete the account setup process. Set a password for your Xero account, and then follow the prompts to set up your business information.

Once your information is set up, click on "Start Free Trial".

Note that you won't need to actively use this trial Xero account - it's only needed to complete the process of adding your Xero app.

Log in to Xero

After you have signed up for a Xero, you can log in to Xero to create an "Application".

You can do this by visiting the Xero Developer Center (https://developer.xero.com/) and clicking on "Log in" in the top right corner. Enter your email address and password and click on the "Login" button.

Register a Xero app

After you've registered for a Xero Developer account and are logged in, go to the "My Apps" page from the top navigation.

You can create a new Xero application by clicking on the "New app" button on the "My Apps" page.

This will take you to a form where you can enter the required information about your app:

• App Name: Enter a meaningful name (for example, 'Apideck integration'), since when your users link their Xero account, they will see the “App Name” is requesting to integrate with their Xero account.
• Integration Type: Select "Web app" as the type of integration.
• Company or Application URL: The homepage of your company’s website or the URL your SaaS product.
• Redirect URI: The URL where the user will be redirected after granting your app access to their Xero account. This should be

  https://unify.apideck.com/vault/callback

  .

Configure your Xero app

After creating your app, you'll need to configure it by setting up various settings and permissions. This includes setting up OAuth 2.0 authentication, and configuring your app's terms & conditions, branding and icons.

App details

The app details allow you to configure the name, company URL, Privacy policy & Terms and Conditions.

Configure OAuth

The next step is to configure the OAuth 2.0 authentication.

Review the "Redirect URIs" and make sure that the URI refers to https://unify.apideck.com/vault/callback

The Client ID is automatically generated. For enabling the OAuth 2.0 authentication, you need to generate a Client Secret.

Click on the "Generate new secret" button to generate a new Client Secret.

💡 TIP: Copy the "Client Id" and the "Client secret". You will need them in the next step.

Vault Connection Setup

Now that you have your Xero App credentials, you can enable the integration to connect to your Xero instance in a secure manner. Once this is done you can start testing it by using Xero's APIs and sandbox environment. You can also use Xero's sandbox environment to test your app's integration with Xero without affecting real data.

Goto the Apideck > Configuration > Accounting > Xero

Enter the OAuth client ID & Secret from Xero and review if the scopes granted in Xero match with the scopes you are requesting in Apideck.

Press "Save settings" to save your credentials.

You can test the connection by clicking "Test Vault", which will check if the connection is working.

Now you are ready and clients can authorize the connection to their Xero account securely.

Do your first API call to the Xero API

• Connect your Xero account through Vault with a test session.

• To test the access token, make a query to get your

  Invoices

  endpoint using the Accouting API.

curl --location --request GET 'https://unify.apideck.com/accounting/invoices' \
--header 'x-apideck-consumer-id: test-consumer' \
--header 'x-apideck-app-id: {APIDECK_APP_ID}' \
--header 'x-apideck-service-id: xero' \
--header 'Authorization: Bearer {APIDECK_API_KEY}'
--header 'Content-Type: application/json' \

Custom Apideck Vault redirect URI options

To enable the connection to your Xero instance and be compliant with the Xero certification, it is required to hide references to any integration platform.

The only reference to Apideck would be OAuth "Redirect URI" after completing the authorization pop-up by customers. The OAuth Redirect URI is hosted by Apideck's Vault.

We have the option to hide the reference to Apideck's Vault callback URL by setting up a custom domain for Apideck Vault.

💡 IMPORTANT: Once you have applied one of the options, don't forget to update the "Redirect URI" in your Xero app configuration.

Setup a custom subdomain for Apideck Vault

Add a custom domain name for Apideck Vault. This will allow you to hide the reference to Apideck's Vault.

1. Create a CNAME record

Sign in to your DNS name server host and navigate to your DNS settings. Add a CNAME record with the value

cname.vercel-dns.com

[REPLACE_WITH_DESIRED_SUBDOMAIN] CNAME cname.vercel-dns.com.

2. Contact Apideck

Get in touch with your Apideck contact to let us know about the custom domain you want to use, so we can configure & enable it for Apideck Vault.

3. Wait for the changes to propagate

Congratulations! You have now pointed your custom domain to Apideck Vault! When DNS changes are made, you can expect a propagation time up to 24 hours (but mostly much less than that). This is because it takes time for the DNS to take effect across the internet. The actual time of propagation may vary in some locations based on your network setup.

4. Update the "Redirect URI"

Update the "Redirect URI" in your Xero app configuration to use your custom domain.

Add an additional "Redirect URI"

https://[REPLACE_WITH_DESIRED_DOMAIN]/vault/callback

https://unify.apideck.com/vault/callback

https://[REPLACE_WITH_DESIRED_DOMAIN]/vault/callback

Submit your Xero app for certification

Once you've finished testing your app, you'll need to submit it for approval by Xero.

You can do this from the Xero Developer Center by navigating to My apps > App Store Application

Xero has a strict app review process to ensure that all apps meet their quality standards and comply with their usage guidelines. If your app is approved, it will be listed in the Xero App Marketplace and available for other Xero users to use.

Visit the Xero App partner page for more information on the advantages.

Xero Webhook Registration

Register a Xero webhook in Unify

Goto the Apideck > Configuration > Accounting > Xero On the Unify Xero connector settings, at the bottom, you can find the “Webhook Execute URL” (1).

💡 IMPORTANT: Copy the full “Webhook execute URL” since you need this URL to register it in Xero.

Create a webhook subscription in Xero

To register a webhook using the Xero Developer Portal, follow these steps:

1. Log in to your Xero Developer account and go to the "My Apps" page from the top navigation.

2. Select the Xero app that you want to register the webhook for.

3. In the side menu of the Xero, click on the "Webhooks" submenu.

4. Subscribe Xero webhook events

To subscribe to Xero change events, you have to enter the Apidek "Webhook execute URL" (1) and press save.

After you have successfully registered the Webhook in Xero, the Webhook key (2) will be generated and displayed on the "Webhooks" page.

Copy the Webhook key (2) from Xero and use it in your Xero Apideck configuration.

5. Register Xero Webhook key in Unify

Goto the Apideck > Configuration > Accounting > Xero

Enter the Webhook key (2) from Xero in the signature key (2) field in Apideck and press Save settings.

6. Trigger the "Intent To Receive" in Xero

The next step is to trigger the "Intent To Receive" in Xero to let Xero validate the webhook key.

This will be handled automatically by Apideck when you have entered the signature key and updates the status in Xero on success.

Subscribe to Unify events

After you have completed the above steps, you can subscribe to your application to Unify Events.

The following guide will explain all the steps to subscribe to Unify webhooks events: How to subscribe to webhook events

FAQ and troubleshooting

1. Limitations and Rules for Updating Xero Invoices

When updating invoices in Xero, there are several limitations and rules you must adhere to:

• You can only update an invoice depending on the type of invoice, and its payment status.

  	ACCREC	ACCPAY
  Unpaid	Yes	Yes
  Paid (in part, or in full)	Yes – with exceptions below	No
  In a locked period	No	No

• If an invoice is paid in part or in full, you can only update the following fields:

  • reference
  • due_date
  • number
  • template_id
  • customer object, unless the payment is made with a Credit Note
  • source_document_url
  • line_items
    • description
    • ledger_account.code, except for Construction Industry Scheme (CIS) account codes

• Creating, updating and deleting line items when updating invoices:

  • In an update (POST) request:
    • Providing an existing line_item with its line_item.id will update that line item.
    • Providing a line_item with no line_item.id will create a new line item.
    • Not providing an existing line_item with its line_item.id will result in that line item being deleted.

2. cURL Requests for Adding and Removing Allocations from Xero Credit Note

Adding Allocations to a Credit Note

To add allocations to a credit note, you can use the following cURL request in proxy with your credit note id and invoice id:

curl --location --request PUT 'https://unify.apideck.com/proxy' \
--header 'x-apideck-consumer-id: {consumer_id}' \
--header 'x-apideck-app-id: {app_id}' \
--header 'x-apideck-service-id: xero' \
--header 'x-apideck-downstream-url: https://api.xero.com/api.xro/2.0/CreditNotes/{creditNoteId}/Allocations' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "Amount": {amount},
  "Invoice": {
    "InvoiceID": "{invoiceId}"
  }
}
'

Removing Allocations from a Credit Note

To remove allocations from a credit note, you can use the following cURL request in proxy with your credit note id and allocation id:

curl --location --request DELETE 'https://unify.apideck.com/proxy' \
--header 'x-apideck-consumer-id: {consumer_id}' \
--header 'x-apideck-app-id: {app_id}' \
--header 'x-apideck-service-id: xero' \
--header 'x-apideck-downstream-url: https://api.xero.com/api.xro/2.0/CreditNotes/{creditNoteId}/Allocations/{allocationId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \