# Create an integration

## Setup your environment

1. Create a local development environment for your North Commerce integration
2. Create a folder `/wp-content/plugins/north-commerce-integration-boilerplate/`
3. Clone the boilerplate from [https://github.com/kelleymuro/north-commerce-addon-boilerplate ](<https://github.com/kelleymuro/north-commerce-addon-boilerplate >)
4. Remove .git and .gitignore or modify them to your own needs
5. Change info.json
   1. Replace {variables} to your own values. E.g plugin Name, last\_updated, description, etc.

## Run the generator

In your browser visit **your-domain.local/wp-content/plugins/north-commerce-integration- boilerplate/integration-boilerplate-generator.php**

Once the generator has ran rename the plugin folder `north-commerce-integration-boilerplate` to `north-commerce-{slug}`&#x20;

{% hint style="info" %}
Remove the generator file from the project now that it is no longer needed /wp-content/plugins/north-commerce-shipstation/integration-boilerplate- generator.php&#x20;
{% endhint %}

## Have fun!

Modify the README.txt file and modify the plugin code to suit your needs for an integration

## Plugin Structure

In the boilerplate plugin you will notice a few folders and files.&#x20;

1. `admin` - This folder contains files for the plugin's admin panel in WordPress
2. `assets` - This folder contains css, js and image files for your integration
3. `includes` - This folder contains plugin functionality files or "the business logic"
4. `includes/integrations` - This folder contains examples and code to integrate with a required service. You will see examples with Shipstation
5. `integration-boilerplate-generator.php` - This file is used to modify the initial plugin code according to your parameters from the info.json. It is needed only once at the beginning of plugin creation. Please dont forget to delete after running the generator from your browser.
6. `info.json` - This files is required to initalize the plugin generator. This file also is necessary to specify plugin version anmd to update your plugin from a server in the future.&#x20;
7. `README.txt` - The plugin requires a standard `README.txt` file containing the plugin description and version history

#### Webhook Integration

File: `includes/integrations/class-north-commerce-webhooks.php`

* Designed to create webhooks for required Events in the "north-commerce" plugin
* Reference implementation available at: `north-commerce-addon-boilerplate/includes/integrations/class-north-commerce-webhooks.php`

#### REST API Integration

File: `includes/integrations/class-north-commerce-plugin-rest-api.php`

* Creates new REST API endpoints for Event-triggered functionality
* Reference implementation available at: `north-commerce-addon-boilerplate/includes/integrations/class-north-commerce-plugin-rest-api.php`

#### Service Integration

File: `includes/integrations/class-north-commerce-send-order.php`

* Contains the core service integration code

### Server Deployment

1. Access the server via FTP using "north-commerce" credentials
2. Navigate to `/var/convesio/wordpress/addons`
3. Create a new folder with naming convention: `north-commerce-{your-plugin-name}`
4. Copy the following files to the folder:
   * `info.json` (from plugin folder)
   * `screenshot-1.jpg` (plugin screenshot)
   * `north-commerce-slug.zip` (plugin archive excluding `.git`, `.gitignore`, etc.)

### Integration Setup

#### Create Integration Placeholder

1. Navigate to `north-commerce/admin/core/integration/placeholders/`
2. Create a new placeholder class file following existing patterns
   * Set `OPTIONAL_KEY = '{slug}_service'`
   * Match existing placeholder implementations

#### Update Integration Class

1. Open `north-commerce/admin/class-north-commerce-integration.php`
2. Add new integration code block in `define_integration_placeholders()`:

```php
phpCopyif ( empty( $this->integration_services['{slug}_service'] ) ) {
    $this->integration_placeholders[ North_Commerce_{Name}_Placeholder::OPTIONAL_KEY ] = [
        'object' => new North_Commerce_{Name}_Placeholder(),
    ];
}
```

3. Deploy updated "north-commerce" plugin to Github

### Plugin Updates

#### Version Update Process

1. Update version number in main plugin file header:

   ```php
   Version: X.Y.Z // Increment by 0.0.1
   ```
2. Update `info.json`:
   * Update `version` field
   * Update `last_updated` timestamp (format: "YYYY-MM-DD HH:MM:SS")
   * Add changelog entry

#### Deployment Process

1. Push updated plugin to Github
2. Create plugin archive (excluding `.git`, `.gitignore`, etc.)
3. Upload via FTP:
   * Archive to `/var/convesio/wordpress/addons/your-plugin/`
   * Updated `info.json` to same directory

#### Update Hooks

The plugin update process utilizes three hooks in the main plugin file. Reference implementation available at: `north-commerce-shipstation/north-commerce-shipstation.php`

### Best Practices

* Always prefix plugin folders with `north-commerce-`
* Maintain clean archives (exclude development files)
* Follow version numbering convention (increment by 0.0.1)
* Keep changelog entries descriptive and dated


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.northcommerce.com/north-commerce/integrations/create-an-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.